Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Wednesday, 30 December 2015 at 00:32:31 UTC, Andrei 
Alexandrescu wrote:
> Then why document it?

Just on principle, a documentation tool probably shouldn't be 
limiting the author's ability to document...

This might just be a bug in dmd btw. Looking at the ddoc spec 
page, it says "documentation comments not associated with a 
declaration are ignored", but it doesn't say the declaration must 
be named.

Perhaps dmd ought to be keeping it but isn't.


> If it's for SEO, what SEO scenarios woukd be covered by this 
> feature that can't be done with simple workarounds? -- Andrei

Putting one item per page is far more important than I even 
realized before getting into this. I was talking to a friend on 
Sunday night about his early adventures into D. He's managed to 
convert one of his work scripts that works with Google Docs to D 
and is working on transitioning a little web form program too.

He consistently found the dlang.org documentation to be 
undiscoverable and nearly unusable once he did find it. One 
example he gave as wondering if D had an Array.join function like 
Javascript.

He searched for "dlang array join" and first, of course, got "did 
you mean golang?". I like to joke about that being Google's bias, 
but I betcha it is actually more to do with our poor SEO than any 
nefarious code on their end.

The top two results he got were:

http://dlang.org/spec/arrays.html

which is no help, it talks about arrays but not the join function

and

http://dlang.org/phobos/std_array.html

which he thought was another false positive because it looked 
generic again. I told him it *is* the right page... but the wrong 
section. To actually get to the join function, you need to find 
it again in the table and hit that second link.


He spent more time than he should have and thought D didn't have 
an array.join function because the search engine didn't actually 
return it. It returned two pages that are vaguely related but not 
specifically what he wanted, and being used to more relevant 
search requests, wrote off the ddoc as a false positive despite 
it being the right page!

I asked people in the #d chatroom to repeat this experiment. 
Nobody even got http://dlang.org/phobos/std_array.html as the top 
result! Longer time D users did get 
http://dlang.org/library/std/array/join.html as a top result - 
good - but nobody actually got the official doc and the ddox only 
came to those with personalized search that ups the rank score of 
D related pages.


Contrast that to even the primitive results from my dpldocs.info 
D-specific search. Look for "array join" and get:


http://dpldocs.info/search/search2?searchTerm=array+join


Whoa, std.array.join is right at the top! And if you click it, 
you go directly to the relevant function doc.


That's huge.