Our docs should be more beautiful

[bitwise 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

Any chance of getting one definition or overload-set per page?

I've never liked the way that each module, in it's entirety, is 
all dumped into a single page. Finding what you're looking for is 
often difficult among all the noise. It's also very easy to 
scroll past what you're looking for. If each definition or 
overload-set had it's own page, issues like vertical spacing 
would be at least, tolerable.

Example:
https://msdn.microsoft.com/en-us/library/bb354760(v=vs.100).aspx

On the left, is all overloads of Enumerable.Average. The full 
path of whatever nested scope you're in is listed along the top. 
If you navigate back(up one scope level), you'll see the 
module/namespace's contents grouped by type(method, property, 
etc..), and each one has nothing more than a short summary of 
what it does.

imo, the 1 module-per-page setup is a bit of a no-win situation.

     Bit