Some impressions/notes from a new D programmer

[bachmeier]

On Wednesday, 12 February 2020 at 10:39:06 UTC, mark wrote:

> Library Reference Documentation
>
> The Library Reference documentation seems to be a mixed bag. 
> Often I've found a good overview at the start, but then few or 
> no examples in the docs for classes and methods (see e.g., 
> https://dlang.org/phobos/std_zip.html#.ZipArchive).
>
> I don't find the presentation of the member properties and 
> methods very easy to read, but the worst aspect is the lack of 
> examples.

It's a bug if something isn't properly documented, whatever the 
flaw may be. It's gotten a lot better in the time that I've been 
using D, but there are still a few rough spots.

My strategy has been to ask for an example in the forum. I then 
click "Improve this page" in the upper right corner and it's a 
simple process to create a PR with the example added. Most of the 
documentation PRs I've created have been merged within a fwe 
hours. If you don't want to do that, you can create an issue in 
Bugzilla, with a detailed explanation of what you were doing and 
what the documentation should show instead.

It would be nice for this to already be done, and while it's 
generally good by the standards of programming languages, there 
are still some weak spots. Anyone can help fix them. In some 
cases when I've reported missing documentation, there actually 
*was* documentation but it wasn't getting added to the website 
for some reason. Nobody will know until it's pointed out. And 
nobody's going to shout at you for filing too many documentation 
bugs or creating too many PRs to fix documentation bugs.