On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
> Let's crowdsource the review. Please check the entries linked from here:
> http://dlang.org/library/index.html.

Looks nice! And will provide motivation to fix a lot of the under-documented functions.

On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
> Let's crowdsource the review. Please check the entries linked from here:
> http://dlang.org/library/index.html.

In:

  http://dlang.org/library/std/algorithm/make_index.html

if you click on the 'forward' link, it takes you to something quite unexpected. Looks like an issue with automatic cross referencing?

On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
> Let's crowdsource the review. Please check the entries linked from here:
> http://dlang.org/library/index.html.

The table:

  http://dlang.org/phobos/std_math.html#.cos

got lost:

  http://dlang.org/library/std/math/cos.html

Also, the 2$(SUP 64). got turned into 2,64.

On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
> 
> Andrei

On that page itself, the descriptions for at least std.regex and std.uni include the headers (e.g Intro, Overview) from those pages.

-- 
Paul O'Neil
Github / IRC: todayman

On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
>
> Andrei

Very first function I looked at: http://dlang.org/library/std/string/format.html

I find all the horizontal bar's throughout the docs quite noisy and tiring, and somewhat antiquated stylistically.

I expected the parameters to jump out at me, but I didn't notice that that block surrounded by black lines and bold headings was actually the parameter list. I don't think I need headings to tell me which column is the name and which is the description. Ie, the parameters didn't jump out at me, the noise surrounding them did, and distracted me from the parameters themselves.

There's obviously a bug here where the text is red too.

My suggestions to make that page look more professional:

* Prototype needs proper syntax highlighting, and elements (builtin
types, types, template args, runtime args, and the function name
itself) need to be styled distinctly (and tastefully).
* The noise around the parameter listing can be removed completely.
* The parameter name string in the parameter listing should match the
styling of the prototype, so you can immediately recognise the thing
in the prototype's description on the page.
* The coloured box that houses the prototype is 6 times wider than it
needs to be (on my monitor). I think it should be horizontally sized
to fit the content.
* Authors, license, and other uninteresting information should be
spaced from the content (give an extra line-break or 2), and also the
text should be significantly smaller. This is, literally, the
fine-print.

Comment box at the bottom is awesome!

Taking another random sample: http://dlang.org/library/std/csv.html

My previous criticisms stand equally.
I feel like 'see also' should be the last thing before the 'fine
print', not the first thing.

Clicking through to see a class: http://dlang.org/library/std/csv/csv_exception.html

Prior criticisms apply, but looks okay otherwise.
There is 'fields' and 'methods', but they look the same. This is
unexpected, since methods are functions, with return types, and
arguments... why can't I see those?

I'll leave it there for a moment.


How do we style this stuff? Is there some way that we can experiment with styling ourselves?

On Tue, 06 Jan 2015 14:43:45 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com>
wrote:

> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
so looking at the function documentation i lost that nice indexes. if i got to the function directly (which will be very likely with googling), now i have to either drop keyboard and use mouse to click on module name (which is not immideately pops like a link, btw), possibly scrolling the page to top, or try to use keyboard navigation, which has only one thing in common for various browsers: it's awful. on the previous version it was not only enough to press "home" and see that, i was able to start quicksearching for other functions and read all the documentation without reloading the page (now two pages, actually).

i don't know about others, but for me new version is like a modern smartphone: shiny, cool, looking pretty and making phone talks worser.

On 1/6/15 6:17 PM, Steven Schveighoffer wrote:
> On 1/6/15 5:43 PM, Andrei Alexandrescu wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>
> std.algorithm has many of the "descriptions" showing samples. Also, I
> know the table at the top is to make things easier for standard ddoc,
> should that be removed?

But I like it.

> BTW, I'm all for the docs to be switched. Just the cross-referencing
> alone is worth it.

One thing we need to do is offer for each module "view as one page" so people still have that option.


Andrei

On 1/6/15 7:20 PM, Walter Bright wrote:
> On 1/6/2015 2:43 PM, Andrei Alexandrescu wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>
> The table:
>
>    http://dlang.org/phobos/std_math.html#.cos
>
> got lost:
>
>    http://dlang.org/library/std/math/cos.html
>
> Also, the 2$(SUP 64). got turned into 2,64.

https://github.com/D-Programming-Language/phobos/commit/7e766e6796a494de5a55c11d106889b47c303eff

Andrei

On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> Let's crowdsource the review. Please check the entries linked from here: http://dlang.org/library/index.html.
>
> Andrei

Another one; I tried to use the search box on the top right corner...
it just resulted in a google search.
Can we do better than that? When people go to the documentation page,
they want to search the docs, not get a standard google results page.

On 1/6/15 7:27 PM, Paul O'Neil wrote:
> On 01/06/2015 05:43 PM, Andrei Alexandrescu wrote:
>> Let's crowdsource the review. Please check the entries linked from here:
>> http://dlang.org/library/index.html.
>>
>> Andrei
>
> On that page itself, the descriptions for at least std.regex and std.uni
> include the headers (e.g Intro, Overview) from those pages.
>
Thanks! -- Andrei