On 1/6/15 8:54 PM, Manu via Digitalmars-d wrote:
On 7 January 2015 at 08:43, Andrei Alexandrescu via Digitalmars-d
<[email protected]> 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.
FWIW the table styling is the least problem with that page. Apparently
the indexer messes up things quite a lot, making text red when it
shouldn't and not rendering code correctly etc.
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.
So Name/Description should go?
Also parameters should be in code font.
There's obviously a bug here where the text is red too.
Yah that's a biggie. Notice the code snippets that were supposed to be
syntax colored too...
Looks like that's a problem in the source. This looks just as bad:
http://dlang.org/phobos/std_string.html#.format
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.
Noice.
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?
Mainly css, see
https://github.com/D-Programming-Language/dlang.org/tree/master/css.
Some styling in the html.ddoc and other .ddoc files, see
https://github.com/D-Programming-Language/dlang.org/tree/master/.
Andrei
