Re: Our docs should be more beautiful
** RANT ON ** A perfect example for an item for your action list. And it pretty much looks like the syntax the wiki is using already. I bet you a drink at next years DConf that it will take you at least 10 minutes to find and reread this thread next time you create a vision document just to rewrite parts of it for you next vision document. ** RANT OFF **
Re: Our docs should be more beautiful
I like this kind of discussion. It's good to make the website look as attractive and functional as we can make it. I think we just need to remember to file each issue individually, then group all of the issues to track all of them. Then each individual issue can be tackled, and some work can get done while the rest of the issues are discussed. Maybe I'm just speaking common sense or something, but I think it's worth mentioning.
Re: Our docs should be more beautiful
I think the Python docs looks better and are more useful...but the older Python docs were even better. Sometimes fancier HTML just makes things less useful. That said, I think that when feasible docs should be auto-generated from code included within the code files. More like ddoc or javadoc then Sphinx or such. But this shouldn't necessarily apply to the basic frameworks. The basic D documentation is extremely good, it's when we get to the libraries that things become a bit iffy. (Then again, I don't like the template syntax. I thought the D1 docs were better than the D2 docs, but this might be because when they were rewritten they assumed things that give me trouble. I prefer the way that Python handles ranges to the way the D does. Etc. These impact the understanding of the documentation of many Phobos files.) On 07/18/2016 06:41 PM, Andrei Alexandrescu via Digitalmars-d wrote: 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
Re: Our docs should be more beautiful
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. I just want to point out that Firefox will sporadically justify incredibly poorly, leaving huge spaces between words (In one extreme case, I caught it making something like 3cm gaps). It looks really bad, and isn't actually easier to read when the line length is long. -Wyatt
Re: Our docs should be more beautiful
On Tuesday, 19 July 2016 at 17:02:34 UTC, Andrei Alexandrescu wrote: On 7/19/16 12:39 PM, bitwise wrote: On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu wrote: 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 Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit The two coexist. -- Andrei Ok, I was under the impression the old ones would eventually be removed. Thanks, Bit
Re: Our docs should be more beautiful
On 7/19/16 12:39 PM, bitwise wrote: On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu wrote: 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 Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit The two coexist. -- Andrei
Re: Our docs should be more beautiful
On Tuesday, 19 July 2016 at 01:37:20 UTC, Andrei Alexandrescu wrote: 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 Why talk about the old style though? I don't see any of the problems you've mentioned in the new beta docs http://dlang.org/library/std/algorithm/searching/balanced_parens.html Bit
Re: Our docs should be more beautiful
On Tuesday, 19 July 2016 at 01:38:54 UTC, Andrei Alexandrescu wrote: ... 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 This is why I don't go through this and help on this matter, I mean the layout is too subjective, I think the left version (Which was changed by my friend) is much better to read than the version on the right. Another thing: using "font-weight" or "bold" sometimes looks weird on high resolutions, which was avoided on the left, maybe is not too visible here but anyway... And finally: Keep in mind that some folks (like myself) use Tablet to read manuals, and the font size matters a lot on tiny screens. By the way, this is not a rant, :) I'm just saying that making layout for others is something that I don't like because the different tastes. Mattcoder.
Re: Our docs should be more beautiful
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.
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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)
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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=mobile Mattcoder.
Re: Our docs should be more beautiful
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.
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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?
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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).
Re: Our docs should be more beautiful
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).
Re: Our docs should be more beautiful
Do we see the same thing? I see ugly justified hyphenated text https://abload.de/img/tmpr5ow8.png
Re: Our docs should be more beautiful
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
Re: Our docs should be more beautiful
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.
Our docs should be more beautiful
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
