• Andrei Alexandrescu (23/23) Nov 16 2017 Whenever I look at the documentation, I find things that could be
• Seb (6/30) Nov 17 2017 This has already been partially fixed at ddox[1], but we can't
• Adam D. Ruppe (13/16) Nov 17 2017 Makes me want to go "fork"-al.

Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:

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

Seb <seb wilzba.ch> writes:

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

Adam D. Ruppe <destructionator gmail.com> writes:

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.