On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:
> I see your point Bauss. I suppose I am not yet experienced enough with D.
Here is an example. Working with one of our programmers, he could not understand the following (sorry for my newbie simplistic example and understanding of D):
The D community so far has said you just need to learn it and the documentation makes sense. I think that summary speaks volumes about missing the point of documentation but that is the reality in D. You have to learn it from books and forum and then you pretty much don't need the documentation.
Just a few days ago, I actually posted about documentation, among other things, but I threw 80% of that reply away because I'm trying to be less negative on the forum. Here is the excerpt:
In fact, I'm on the forum right now because I was looking for a map function in D. Here it is:
https://dlang.org/library/std/algorithm/iteration/map.map.html.
The map function is there and it works really well. But go ask 10 of your co-workers (that haven't used D) how this function works and maybe 2 or 3 can even guess something close. I don't even know for sure how I specify the mapping function (sometimes it's a function, sometimes it's a string) but with a bit of trial and error, I'll figure it out. There's not even an example of usage in the documentation.
The documentation is not good is not a way to learn D, although it is somewhat useful. If you want your team to learn and get familiar with D enough to use the documentation, I would suggest you get Andrei's and Adam's books. There are other good books as well I'm sure, but I have not read them. Some sit in my Amazon cart where I covet them from time to time. ;) You might find comments about them being out of date, but by the time your colleagues are done with them, they will be able to understand the documentation.
I hate to bug people on the forum, but I know if I have a question, I will get a response by the next day, but usually a lot faster than that.
So if I were you, I would solve the immediate problem by getting and distributing those book as well as inviting your colleagues onto the forum if they have questions you can't answer.
In the medium term, you could start a knowledge base or documentation site or maybe join one of the dozens of others that undoubtedly exist.
The long term problem is harder to address. Until building documentation, tools and library is sustainable, people won't do it. I have spent a lot of effort on projects that die (including D programs, as it happens) and I have a lot going on in my life. It's going to take a large effort to establish clear goals and visions with a known way to work on them or it may take forking the language and leaving one stable for a bit before people decide. I hope that happens before another language enters D's odd niche.
Permalink
Reply
