Suggestion re the manual

[harakim]

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.