Better docs for D (WIP)

default0 via Digitalmars-d-announce digitalmars-d-announce at puremagic.com
Wed Dec 30 06:25:24 PST 2015


On Wednesday, 30 December 2015 at 04:03:42 UTC, Andrei 
Alexandrescu wrote:
> On 12/29/2015 09:09 PM, Adam D. Ruppe wrote:
>> Putting one item per page is far more important than I even 
>> realized
>> before getting into this.
>
> We already have that:
>
> https://dlang.org/library/std/array/join.html
>
> If I search for dlang array join that the third hit on google 
> if I'm logged in, and the SECOND hit if I use an anonymous 
> session that gives google no information about my searching 
> habits.

Can confirm these search results.
As an aside, the mere formatting of the list of 
template-constraints on the dlang page made me nope right out of 
even bothering to figure out how to read them or what the 
difference between the first and the second overload of join was.
Checking dpldocs for proper formatting and spending half a minute 
making sense of it I figured that the one was for an exactly 
matched element type and the other one was to allow joining a 
baseClass[][] with a subClass[] or something along those lines.

Plus, it's of course really nice that we have these single pages, 
but for most things you search in google you still get results 
that lead you to http://dlang.org/phobos/ with pages that usually 
make your scrollbar pretty tiny and forcing you to either 
Ctrl+F-guess your way through the page or figuring out what 
function out of a list of 10-30 functions might possibly suit 
your need only to scroll back up again and repeat (or look at 
another module altogether) if it doesn't. Cumbersome and annoying 
(ie: slow and unproductive).

Also the information that /library even exists is new to me. I 
have only discovered it through reading this post. So that much 
for its discoverability (I am new to D, but I did spend probably 
something like 5-10 hours bugging around phobos documentation by 
this point and never really knew of /library).

Example searches I did:
http://puu.sh/mdGTt/e71cc7e459.png (only phobos)
http://puu.sh/mdGX8/24250120b1.png (first two results /phobos, 
third /library)
http://puu.sh/mdH5W/31d3a2432a.png (should be 
https://dlang.org/library/std/base64/base64_impl.decode.html 
ideally, but the module overview pages have examples, so this is 
kind of okay)
http://puu.sh/mdH8g/42a82217e0.png (none of these results mention 
that you should simply cast(char[]) and then call validate on the 
casted array, from what I could tell skimming through them for 5 
minutes, I might have missed a mention though, which would simply 
mean it is not obvious enough)

So yeah, we have that, but it should be promoted more, and the 
documentation still needs lots of love (think the type of 
formatting and interlinking (even to concepts!) that adams 
documentation does, and of course the general deal with we need 
more examples and whatnot).


More information about the Digitalmars-d-announce mailing list