Suggestion re the manual

[Paul]

On Wednesday, 8 June 2022 at 08:26:02 UTC, bauss wrote:
> On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:
>> I am not an expert programmer (although I work in software 
>> every day). I'm more of a system designer. Dlang has really 
>> made a big difference in our little company and we are truly 
>> grateful to have it. However, one thing I miss from my PHP 
>> days (I know - script languages - Ugh), is having public 
>> comments below each manual page.
>>
>> Having the public post examples, gotchas, and other helpful 
>> information made a world of difference in learning the PHP 
>> language, all the while having the "source of truth" directly 
>> above.
>>
>> Just suggesting that it might help increase adoption rates 
>> (PHP is very popular). Managing comments does take time, but 
>> then so does managing this forum.
>>
>> Anyway, no ideas are bad ideas, so I felt I should post. I 
>> hope it is helpful.
>
> Personally, I don't like it. I don't think good documentation 
> needs comments to explain the content.
>
> The reason why it's good for PHP is mostly because of how 
> unintuitive and inconsistent it really is sometimes.
>
> As you said yourself, it's good for gotchas etc.
>
> D doesn't really have any gotchas in that sense since it's much 
> more strict, not just in the sense of its language, but also 
> how the standard library is written.
>
> Most gotchas in PHP stem from inconsistent function names, 
> arguments and the fact it's dynamic typing.
>
> D has very consistent naming of functions, order of arguments 
> and it's static typed.
>
> Most other language documentations don't have a comment section 
> either and probably because they're documented well too.
>
> While PHP has improved and keeps improving, then it still let's 
> most of is garbage linger around.

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):

if ( a_name.exists ) ...

Where a_name is a string argument passed into the function. He 
felt that it was checking if the string has a value and could not 
understand why. It was a surprise to find that "exists" is 
actually a uniquely named D function that actually means 
"fileexists". Same with copy and remove.

Later, a more senior developer suggested we alias these names to 
be more readable, and easier to search for (we have a mix of D 
code, JS, and even our own class methods with similar names).

Maybe public comments like this within the manual could help with 
understanding and help improve the accessibility and adoption of 
D?

Regardless, D is wonderful, and we are thankful to have it. We 
hope D achieves widespread adoption it so that our company can 
rest assured that the project will live on. Sadly, a big deciding 
factor is risk mitigation (particularly by venture capitalists) 
and access to experience developers, who are all looking at this 
in the same way. It is very frustrating to hear "Why would we 
want to code in D? Who uses D?" when we know with 100% certainty 
that D significantly reduces our development time, and increases 
the reliability and maintainability of our software. And 
likewise, when a programmer says "I cannot understand the manual. 
It seems to be written for D experts only" it feels like a punch 
to the gut.

D is brilliant once you get into it. We will do whatever we can 
to help it spread.

Thank you for listening.