Our docs should be more beautiful

[Carl Vogel via Digitalmars-d]

On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu 
wrote:
> I was proofreading 
> http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/phobos-prerelease/std_experimental_checkedint.html and there are a few ways in which our docs could look better.
>
> * My pet dream was to work on a project with a beautiful 
> justified and hyphenated website. After endless debates, 
> ugliness has won - I'm looking at a eye-scratching ragged right 
> edge.
>
> * The constraint on "struct Checked" is not formatted the same 
> as the other constraints.
>
> * Vertical spacing is just too fluffy. Looking e.g. at the docs 
> for "Payload" and "hook" - each has a short description. The 
> vspace between definition and description is too tall. The 
> vspace between the description and the next definition is too 
> tall. The grayed space within which the definition itself sits 
> has too large up and bottom margins. The vspace above "Jump 
> to:" is too high. Literally all vertical spacing is larger than 
> it should be.
>
> * The red vertical line on the left of each definition is meh. 
> There's a bit more sense for struct definitions because of the 
> "Jump to:" real estate. But for each little one-line 
> definition, the red bar is just odd. Also, there is no change 
> in color as indentation goes in (which would be a useful cue 
> for long struct definitions).
>
> * I don't see a point to the boxes within which each definition 
> + its comments sits. Then there's one more box for the example! 
> Boxes, boxes everywhere, and nary a drop to drink. They'd make 
> sense e.g. if one could collapse a box. As such - hey, they 
> just add more vspace :o).
>
> * The vspace between the ditto'ed definitions "enum auto min;" 
> and "enum auto max;" is again too large.
>
> * The grayed out constraints are also indented horizontally - 
> by a lot. If they're already distinguished by color, no need to 
> indent them. Oh, then I saw if you hover you see "Constraints: 
> " written in the space that seem to be indentation. Could we 
> format that in non-code font at least?
>
> * Spacing between doc paragraphs (see e.g. doc of opCast) seems 
> to be 80% line height. Should be 50%.
>
> * The enumerated items (see doc of opChecked) seem to be the 
> only artifact that's properly spaced vertically. I guess nobody 
> discovered them so they're at the system default.
>
> * "0 Contributors" should not be displayed at the bottom if 
> there are no contributors. But I assume that's only the case 
> before the pull is merged?
>
>
> Andrei

I'm not going to get involved this round of bikeshedding, (except 
to say that yes, the docs are far from perfect, and also that 
justification/hyphenation on the Web is a mixed bag, and 
right-ragged with a good line-length is a fine and robust 
solution).

But I'd like to give some resources for reference. Racket's docs 
have actually been designed by a professional typographer, so 
might be a good reference point. Example: 
https://docs.racket-lang.org/reference/flonums.html

And that the same person has an excellent online resource for 
typographic style:
http://practicaltypography.com/

And it's good to have something like that (no matter if it's 
somewhat arbitrary) to decide these kinds of endlessly debatable 
issues. (Notice the site is left-justified/right-ragged :))

"Keep in mind that the jus­ti­fi­ca­tion en­gine of a word 
proces­sor or web browser is rudi­men­tary com­pared to that of a 
pro­fes­sional page-lay­out pro­gram. So if I’m mak­ing a 
word-proces­sor doc­u­ment or web page, I’ll al­ways left-align 
the text, be­cause jus­ti­fi­ca­tion can look clunky and coarse. 
Whereas if I’m us­ing a pro­fes­sional lay­out pro­gram, I might 
justify." (http://practicaltypography.com/justified-text.html)