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!

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

> 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/

This is a working link:

https://dlang.org/blog/2020/02/17/news-update-swag-platforms-documentation-help-and-more/

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

> 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.

Sorry for this not being more specific, but we need a version of Rust's "The Cargo Book" for D:
https://doc.rust-lang.org/cargo/
The reason I can't be more specific is because I don't use Dub except when doing so is trivial.

We need documentation in particular on using Dub with mixed language projects. The obvious case is C and D, but one of our strengths is interoperability with basically all languages, so we should have examples showing how to use Dub with projects containing Fortran, Python, Lua, etc.

On Monday, 17 February 2020 at 12:52:09 UTC, bachmeier wrote:
> Sorry for this not being more specific, but we need a version of Rust's "The Cargo Book" for D:
> https://doc.rust-lang.org/cargo/
> The reason I can't be more specific is because I don't use Dub except when doing so is trivial.
>
> We need documentation in particular on using Dub with mixed language projects. The obvious case is C and D, but one of our strengths is interoperability with basically all languages, so we should have examples showing how to use Dub with projects containing Fortran, Python, Lua, etc.

I'd second this. Figuring out how sub packages work, how to structure a project into different interdependent sub packages, how to fetch dependencies (dub upgrade does not work recursively :() took way too long coming back to D.

Generally a bit of best practice guidelines would be useful, see for example the my current question in the learn forum.

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
> This thread is a place to collect your documentation pain in one place.

The documentation for cross compiling/linking using LDC isn't exactly what I'd call user friendly. It would really help to have a complete example so that someone can be up and running within five minutes. It would also be nice to have an example that avoids Dub altogether, and to the extent that examples do use Dub, they're complete and can be used by a beginner to the language (so at least brief explanations of Dub usage is explained, with links to proper documentation).

On Monday, 17 February 2020 at 15:01:32 UTC, bachmeier wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> This thread is a place to collect your documentation pain in one place.
>
> The documentation for cross compiling/linking using LDC isn't exactly what I'd call user friendly. It would really help to have a complete example so that someone can be up and running within five minutes. It would also be nice to have an example that avoids Dub altogether, and to the extent that examples do use Dub, they're complete and can be used by a beginner to the language (so at least brief explanations of Dub usage is explained, with links to proper documentation).

Sorry, forgot the link to the page that should be improved:
https://wiki.dlang.org/Cross-compiling_with_LDC

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
> This thread is a place to collect your documentation pain in one place.

I once tried to use std.socket:
https://dlang.org/phobos/std_socket.html

Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.

Literally nothing in core.stdc has documentation. Would rather have the documentation be there when you auto complete or 'go to definition' in an editor.

Same with system libraries in core.sys. What's worse there is that the parameter names for the functions are just 'a', 'b', 'c', etc... Instead of the name of the actual argument.

On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> This thread is a place to collect your documentation pain in one place.
>
> I once tried to use std.socket:
> https://dlang.org/phobos/std_socket.html
>
> Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.

Adam D. Ruppe wrote a very good socket tutorial. You can find it here http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html

Kind regards
Andre

On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> This thread is a place to collect your documentation pain in one place.
>
> I once tried to use std.socket:
> https://dlang.org/phobos/std_socket.html
>
> Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.

I think one of these could be incorporated as an example, either Adam's or Ali's code:

https://forum.dlang.org/thread/cexeumxikeovazyotkfl@forum.dlang.org

I always use those when starting a new D networked project.