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:


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

Reply via email to