Documentation Improvement Initiative

[Mathias Lang]

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
> Preliminary discussions are underway for a new event to 
> encourage improvements to documentation across the D ecosystem. 
> I can't provide any details yet because the details aren't yet 
> fixed. I don't even know for sure it's going to happen.
>
> However, the best way to make it happen is for us to have a 
> solid set of well-defined documentation tasks. Putting that 
> together is going to require help from the community. All of us 
> have encountered areas where improvement is needed in the spec, 
> the Phobos docs, and docs for dub, vibe.d, and many other tools 
> and projects around the D ecosystem. Some of it has made it 
> into Bugzilla (which will be mined for material), but much of 
> it has been buried in the forum archives or evaporated into the 
> ether from the IRC/Discord/Slack channels.
>
> This thread is a place to collect your documentation pain in 
> one place. I'm about to publish a blog post announcing this (a 
> few minutes after I hit 'Send' on this post):
>
> http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/
>
> As I mention there, we need you to be as specific as you can. 
> What, specifically, is missing? What is unclear? What is 
> incorrect? Give as much detail as you can. We want to be able 
> to gather this info and define specific documentation tasks 
> that anyone can step in and complete with the information 
> provided.
>
> Any project in the D ecosystem is fair game. So please help us 
> out and tell us how D documentation can be improved for you.
>
> If you feel the urge to wax philosophical on something you see 
> here, please start a new thread and do all the philosophical 
> waxing you want there. Let's keep this one focused on listing 
> specific documentation issues. Do feel free to expand on any 
> post here with information you think is relevant.
>
> Thanks!

1. Dub documentation

DUB needs much, much better documentation. Especially cookbooks 
(there's already some, but it is not accessible enough IMO). 
Example of how to structure a project (writing a library with an 
executable, writing a project with examples that are separate and 
compile, writing a client/server app or any two apps linked 
together, writing a project that interface with C/C++, writing a 
project that use some preprocessor, e.g. dtoh, etc..).

Some of this documentation will *also* require fixes to Dub (e.g. 
https://github.com/dlang/dub/issues/1474 for anything using 
preprocessor). There is a feature that allows a project to 
provide skeleton for apps using it, it might also be useful to 
try to do it with a few projects.

2. DMD documentation

Inexistent. Enough said.

3. C++ interfacing documentation

The documentation for interfacing with C++ is ridiculously 
outdated (e.g. it says that operators overloads are not callable 
from D). I am currently rewriting it.

Also, some other features are not documented. It would be helpful 
to have a language expert going over it and see what missing 
(e.g. yesterday I found out `pragma(crt_{con,de}structor)` was 
missing, despite being in the language since 2018-01-01). But I 
don't have specific example of missing features ATM.

4. Documentation history

https://issues.dlang.org/show_bug.cgi?id=20588

5. More pattern documentation

Some of https://github.com/zhaopuming/awesome-d could be 
integrated in the website, e.g. I've never heard of 
https://garden.dlang.io/ before!
Likewise, http://p0nce.github.io/d-idioms/ provide amazing tips. 
One (anecdotal) example is that `enum` is over-used in the docs 
while `static immutable` (with initializer) should arguably be 
the default for people.