Whenever I look at the documentation, I find things that could be improved. Consider https://dlang.org/library/, one of the most important pages - the portal - of the hopefully future default documentation renderer. It goes something like this:

================
Module	Description
================
std.algorithm.comparison	This is a submodule of std.algorithm. It contains generic comparison algorithms.
std.algorithm.iteration	This is a submodule of std.algorithm. It contains generic iteration algorithms.
std.algorithm.mutation	This is a submodule of std.algorithm. It contains generic mutation algorithms.
std.algorithm.searching	This is a submodule of std.algorithm. It contains generic searching algorithms.
...
================

Makes you want to go postal, innit? Reminds me of this quote from David Foster Wallace's unfinished The Pale King: https://www.goodreads.com/quotes/621837-irrelevant-chris-fogle-turns-a-page-howard-cardwell-turns-a

Can a kind volunteer please put some tender love care into that page?


Thanks,

Andrei

On Friday, 17 November 2017 at 03:04:20 UTC, Andrei Alexandrescu wrote:
> Whenever I look at the documentation, I find things that could be improved. Consider https://dlang.org/library/, one of the most important pages - the portal - of the hopefully future default documentation renderer. It goes something like this:
>
> ================
> Module	Description
> ================
> std.algorithm.comparison	This is a submodule of std.algorithm. It contains generic comparison algorithms.
> std.algorithm.iteration	This is a submodule of std.algorithm. It contains generic iteration algorithms.
> std.algorithm.mutation	This is a submodule of std.algorithm. It contains generic mutation algorithms.
> std.algorithm.searching	This is a submodule of std.algorithm. It contains generic searching algorithms.
> ...
> ================
>
> Makes you want to go postal, innit? Reminds me of this quote from David Foster Wallace's unfinished The Pale King: https://www.goodreads.com/quotes/621837-irrelevant-chris-fogle-turns-a-page-howard-cardwell-turns-a
>
> Can a kind volunteer please put some tender love care into that page?
>
>
> Thanks,
>
> Andrei

This has already been partially fixed at ddox[1], but we can't upgrade ddox for the dlang.org build atm [2].

[1] https://github.com/rejectedsoftware/ddox/pull/165
[2] https://github.com/dlang/dlang.org/pull/1891

On Friday, 17 November 2017 at 03:04:20 UTC, Andrei Alexandrescu wrote:
> Whenever I look at the documentation, I find things that could be improved. [...]
> Makes you want to go postal, innit?

Makes me want to go "fork"-al.

http://dpldocs.info/experimental-docs/std.html
http://dpldocs.info/experimental-docs/std.algorithm.html


There's still stuff I'm not quite happy with, but a huge win on my site is that I change the generator and source code in sync - some of the problems you have pointed out with ddox are the generator's fault and some are Phobos source code tweaks. I think if ddox is going to have similar success, I think the "website doc czar" on your end will have to have authority to edit doc comments in a streamlined process as well as the doc generator. They go hand-in-hand.