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 justification engine of a word
processor or web browser is rudimentary compared to that of a
professional page-layout program. So if I’m making a
word-processor document or web page, I’ll always left-align
the text, because justification can look clunky and coarse.
Whereas if I’m using a professional layout program, I might
justify." (http://practicaltypography.com/justified-text.html)
