On Monday, 18 July 2016 at 22:16:45 UTC, Mattcoder wrote:
> 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.
>>
>> ...
>
> Look over this: changed(left) and the old(right) versions, what you think?
>
> http://i.imgur.com/UTLpK42.png
>
> PS: Click to see the full image.
>
> Mattcoder.

Oh and by the way, we should use something like google page insights or alternatives, because it usually show good points. For example the space between the links, it's frustrating when browsing using mobile and you click on a link and opens the other link.

Google page insights: https://developers.google.com/speed/pagespeed/insights/?url=http%3A%2F%2Fdtest.thecybershadow.net%2Fartifact%2Fwebsite-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564%2Fweb%2Fphobos-prerelease%2Fstd_experimental_checkedint.html&tab=mobile

Mattcoder.

On Monday, 18 July 2016 at 22:13:35 UTC, bitwise wrote:
> Any chance of getting one definition or overload-set per page?

Both the ddox pages at /library and my pages at dpldocs.info do it this way. The ddox ones are supposed to be made default eventually.

http://dlang.org/phobos/std_algorithm_searching.html#.balancedParens

vs

http://dlang.org/library/std/algorithm/searching/balanced_parens.html

vs

http://dpldocs.info/experimental-docs/std.algorithm.searching.balancedParens.html

On Monday, 18 July 2016 at 22:24:09 UTC, Adam D. Ruppe wrote:
> On Monday, 18 July 2016 at 22:13:35 UTC, bitwise wrote:
>> Any chance of getting one definition or overload-set per page?
>
> Both the ddox pages at /library and my pages at dpldocs.info do it this way. The ddox ones are supposed to be made default eventually.
>
> http://dlang.org/phobos/std_algorithm_searching.html#.balancedParens
> vs
> http://dlang.org/library/std/algorithm/searching/balanced_parens.html
> vs
> http://dpldocs.info/experimental-docs/std.algorithm.searching.balancedParens.html

Ok, so I'm a little late to the party as usual ;)

This one is pretty much what I'm talking about, except for a few things:
http://dlang.org/library/std/algorithm/searching.html

1) The page heading is confusing. I would either remove "Module", "Template", etc completely, or put them on their own line:

current:
Module std.algorithm.searching

to:
std.algorithm.searching
Module

or(like dpldocs):
std.algorithm.searching

2) I much prefer the navigation structure of the dpldocs as well, in that it only shows the parent scope of whatever you're looking at instead of the current tree structure. At most, I would prefer two levels maximum. Also, I like that top level packages like (std) have a standard looking page like their inner modules(http://dpldocs.info/experimental-docs/std.html). I think having the entire hierarchy look standard from root to leaf is important.

3) I like the fonts better on the dpldocs, but I think I prefer the current color scheme.

It would be nice to see these changes merged into the beta library reference.

Thanks,
  Bit

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)

On 07/18/2016 06:13 PM, bitwise wrote:
> Any chance of getting one definition or overload-set per page?

Been like that for a while, my comments refer to the old styling. -- Andrei

On 07/18/2016 06:16 PM, Mattcoder wrote:
> 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.
>>
>> ...
>
> Look over this: changed(left) and the old(right) versions, what you think?
>
> http://i.imgur.com/UTLpK42.png
>
> PS: Click to see the full image.

I like the styling on the right - the vertical spacing between paragraph is ridiculous in the left version, and the "Jump to:" box is too tall. -- Andrei

On 07/18/2016 09:28 PM, Carl Vogel wrote:
> 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

They do look nice! -- Andrei

On 07/18/2016 11:56 AM, 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.

BTW, apparently the ddox version is not generated. Should be at:

http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/library-prerelease/std/experimental/checkedint.html

but it's not. Vladimir?


Andrei

On 07/18/2016 09:43 PM, Andrei Alexandrescu wrote:
> On 07/18/2016 11:56 AM, 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.
>
> BTW, apparently the ddox version is not generated. Should be at:
>
> http://dtest.thecybershadow.net/artifact/website-f26d7179b8449e89e1961391fde9f221813c707c-04d0496c2d8cecedc4d75c919646d564/web/library-prerelease/std/experimental/checkedint.html
>
>
> but it's not. Vladimir?

Eh, found it at:

http://dtest.thecybershadow.net/artifact/website-32ee0211c7f70b1a06ed3f6ee49f561bee57fee0-ef296f09c3917e6f329f2ca29cbd9f6a/web/library-prerelease/std/experimental/checkedint.html

The ddox version does look nicer. My only nits there are:

* The red underline for links looks jarring, especially in conjunction with blue code.

* Look, ma, no boxes - awesome. And most horizontal lines are understatedly helpful.

* At the bottom of the page there's an odd "| Page generated by ddox." I suppose something should be before the pipe?

* Well the template constraint is not formatted differently/helpfully. I'm thinking some stylized comments in conjunction with ddox could work miracles here.


Andrei

On Monday, 18 July 2016 at 22:24:09 UTC, Adam D. Ruppe wrote:
> The ddox ones are supposed to be made default eventually.

What is the state on this? I found no issue tracking this.