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?