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

On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu wrote:
> * 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.

Please, no more debates on this.

The web's typographic code is not good enough yet and it looks terrible. Also, bad justified text is a nightmare for people with Dyslexia. My dyslexic friend has many custom styles for sites with justified text just so he can read without a headache.

> * The constraint on "struct Checked" is not formatted the same as the other constraints.

This is a bug. File a report :-) ?

> * 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?

I rather like the indentation. Let's me reduce things that need to be processed visually easily.

> * "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?

Yeah, should be one when it's merged.

On Monday, 18 July 2016 at 16:18:27 UTC, Jack Stouffer wrote:
> On Monday, 18 July 2016 at 15:56:29 UTC, Andrei Alexandrescu wrote:
>> * "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?
>
> Yeah, should be one when it's merged.

Yes. However a PR for this AutoTester edge case has already been submitted ;-)

https://github.com/dlang/dlang.org/pull/1431

Do we see the same thing? I see ugly justified hyphenated text https://abload.de/img/tmpr5ow8.png

On Monday, 18 July 2016 at 17:09:57 UTC, Kagamin wrote:
> Do we see the same thing? I see ugly justified hyphenated text https://abload.de/img/tmpr5ow8.png

It probably depends on the browser. Mine shows the text not justified, and it does not try to break words (while your does). Probably, the CSS does not explicitly state what to do, so the browser applies its own default, which is different between you and me (and Andrei).

On Monday, 18 July 2016 at 17:09:57 UTC, Kagamin wrote:
> Do we see the same thing? I see ugly justified hyphenated text https://abload.de/img/tmpr5ow8.png

It's hyphenated on browsers that support it. The chrome team is very close to supporting hyphenation so it'll soon be justified in all the major browsers (I think they are just trying to decide what to do on desktops browsers that don't have a system-wide hyphenation dictionary).

On 2016-07-18 17:56, Andrei Alexandrescu wrote:

> * My pet dream was to work on a project with a beautiful justified and
> hyphenated website.

I hate when words are split between rows.

-- 
/Jacob Carlborg

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 "ragged" left is more ugly. If you want a be beautiful, the left side should align, but every text is indented differently due to boxes/lines.

> Literally all vertical spacing is larger than it should be.

I would disagree, but at this level it is bike shedding.

There should be more vertical space. For example, I would increase the line height a little and the lines are too wide.

Does it make sense to work on this soon-to-be-replaced styling?

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

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.