docs(project-repo): Add and implement style guidelines for docs

[bandali]

This pull request adds a proposed project-repo/style-guide.md, and updates the existing docs under project-repo/ to implement/follow the proposed style.

I also took the liberty to replace some UTF-8 unicode quotes or ellipsis characters with their ASCII counterpart. I think it would be good to stick to using ASCII where possible, and leave things like 'smart quotes' and other 'prettification' to the typesetter of the docs generation/rendering tools. I'd be happy to add a blurb about this in project-repo/style-guide.md.

[didrocks]

One note before reviewing: I see that you are adding lines breaks at 80 characters. I think, in particular with markdown, we should let the editor and renderer doing this, so that we don’t introduce unnecessary diffs when doing changes (here, the changes are then really hard to find). Also it means some minimal typo fix in a paragraph will then crop to potentially 10 lines diff because you need to drop again at 80 characters for each of them, realigning everything, what do you think?

[bandali]

Hey @didrocks, thanks for the reply!

One note before reviewing: I see that you are adding lines breaks at
80 characters.

Minor nit: I'm actually proposing ~70 characters, rather than 80 :)

I think, in particular with markdown, we should let the editor and
renderer doing this, so that we don’t introduce unnecessary diffs
when doing changes (here, the changes are then really hard to find).
Also it means some minimal typo fix in a paragraph will then crop to
potentially 10 lines diff because you need to drop again at 80
characters for each of them, realigning everything, what do you
think?

While I appreciate the concern, in practice that doesn't seem to
have been much of a problem at least in the cases I've seen in other
free software projects I contribute to that follow this approach:

If the change is indeed a minimal typo fix (like rearranging the
order of some characters or words, or adding/removing one or two
characters), chances are that after the fixes the affected lines would
still have roughly the same lengths as they did before, so there may
be no need to rewrap them.

Also, if you consider the wording of the proposed guidelines, it says
"try to limit lines to about 70 characters", meaning the proposed
length is more of a suggestion rather a hard limit, so it's okay
to occasionally have slightly longer lines (e.g. up to 80 characters)
or to not rewrap the paragraph with every single change, but to do so
when the lines of the paragraph are beginning to be visually varied in
length. (I'm happy to more explicitly mention this in the guidelines.)

Even so, with a decent diff tool, the rewrapping doesn't look so bad.
Here's a screenshot from a diff in GNU Emacs:

As for readability of diffs, I've found manually-wrapped doc files
to generally produce more manageable/readable diffs than those with
super long lines, especially if the diff tool at hand does not produce
character-level diffs (highlighting the exact changed characters in a
more prominent colour than the rest of the line).

What do you think?

[didrocks]

No worry!

Minor nit: I'm actually proposing ~70 characters, rather than 80 :)

It’s even worse ! :p

Also, the issue is that by having this break at approximately this, some people like arbitrarely break before some prefix, with the article, pre or post… Markdown supports long lines and self breaking in the renderer, editor can autowrap lines visually some lines from us, so there is no technicaly limitations on that side, let’s maybe not impose some on us?

My main issue is that those guidelines should be agreed widely. For instance if I take your:

Also, if you consider the wording of the proposed guidelines, it says "try to limit lines to about 70 characters", meaning the proposed length is more of a suggestion rather a hard limit,

Right, but here, for instance, you say it’s a proposal and you change existing files to follow this proposal. So, if we don’t enforce one rule, we will end up with a mix of style per file, or within the file, or like in that case, a huge diff to review for some personal preferences.

Even so, with a decent diff tool, the rewrapping doesn't look so bad. Here's a screenshot from a diff in GNU Emacs:

Indeed, but most of the reviews are going to happen on Launchpad or GitHub, those don’t support the rich diff (look at the diff of this PR alone!).

Also, from an editor perspective, I really feel that the editor itself is able to self-wrap at the amount of characters you want without introducing a line break.

I’ll let other comments on their opinions, but to me, I can’t really review this one in the current state. At worst, if we go with 70 characters, I suggest that we have one change with the actual diff, and one to change the wrapping.

[tim-hm]

👍 to a style guide. I'm very much of the opinion that we should follow when there is a clear consensus. So, in my view, we should follow markdownlint for formatting (which afaik doesn't specify hard vs soft wraps). Wrt tone/tense/etc do we have a canonical style guide for writing or do we follow another style guide there?

Wrt line breaks, as with everything there are pros and cons to both! In my view docs are prose not code. Because its prose, I'll read it on various screen sizes / devices and I want the viewport properties of that device to determine line breaks (ie it should be responsive to width and even allow me to specify my own desired width in my renderer). For example in this thread, @bandali0's reply does expand/shrink correctly for me. If I have a narrow view (phone) then the line breaks are messed up and I get partial sentences on a line making it difficult to read. If I have a wide view say on a 4k monitor then it looks oddly padded.

Personally I find long lines difficult to read/track, but in that case I'd rather have the view respect the width I put my window at so I can adjust for my optimal setting.

So in sum, I'm 👎 to hard line breaks in the docs.

[tim-hm]

Whats the view on line width for commit mesages?

[jibel]

I agree with Tim and Didier on the line length. It shouldn't be forcibly and artificially wrapped and let the editor do its job so it fits everyone's display.

However, for the commit messages, they'll potentially end up in changelogs and some tools like lintian require lines shorter than 80 characters. For instance the line too long tag says:

Tag: debian-changelog-line-too-long
Severity: warning
Check: debian/changelog
Explanation: The given line of the latest changelog entry is over 80 columns.
 Such changelog entries may look poor in terminal windows and mail
 messages and be annoying to read. Please wrap changelog entries at 80
 columns or less where possible.

[3v1n0]

Also, from an editor perspective, I really feel that the editor itself is able to self-wrap at the amount of characters you want without introducing a line break.

I personally think that keeping a reasonable line length is still very important, and while I was more liberal on that, the more I'm getting old the more I stress on this. Despite the fact that editors can do line wrap or resolution has changed, for various reasons:

• Human being is better at doing vertical reading while going very wide makes reading harder. This is true not only for code and docs but also in normal literature, where indeed there are standards for a maximum line length for the same reason (some reasoning behind is here but you can find hundreds of articles).
• You may reply that editors can do line wrapping.
  That's true but that clashes with raw text and markdown that ideally should be very well readable in an
  80-chars wide terminal and when rendered in a rich-text editor.
  Try to read a dotted-list with very long lines in a text editor, with line wrapping enabled: It looks bad and it's hard to follow, while using a shorter line weight accommodates both usages.
• Bad for diff: very long lines imply more diff, true that various git renderer support in-word diff, but still it makes things way harder to review
• Bad for markdown syntax: as said before, markdown is designed to be good to read both in source code and when rendered, making not considering that there are users just using text editors around is just wrong.
• Bad for those using multi-column: Indeed now we've high resolution display, but I don't know yourself, instead of giving your eyes a bad time to read, you can take advantage of that by using multiple-columns editors. Which again makes things easily go more vertical and use less horizontal space (isn't this also something that the go happy path somewhat enforces?).
• Bad for people using vertically oriented monitors: as before, if you use a vertically oriented monitor where to put some code in, having long lines makes things hard.

So, to me writing any text (whether is code or not) has to be made independently by the editors or viewers that their users use.
And in general, opening any .md file with less in a tiny terminal should make it as usable as when you use a super-customized IDE that does lots of fancy rendering on top for you.

[3v1n0]

I mean, I'm not sure if it's just me, but even reading the diff of this PR, reading the new part is like a relief, and it would be very hard, if not impossible to compare the previous one with long lines.

At the same time, even any renderer does line wrapping (this is default github one), so having a limit is somewhat needed for readability in any case.

[seb128]

As you said there are pro and con for each approach, I'm just throwing gitlab's guideline as another reference example there

https://docs.gitlab.com/ee/development/documentation/styleguide/#text

To make the source content easy to read, and to more easily compare diffs, follow these best practices when possible.

Split long lines at approximately 100 characters.

(also discussed in more details with screenshots example in https://about.gitlab.com/blog/2016/10/11/wrapping-text/)

The google style guide seems also to suggest wrapping, https://google.github.io/styleguide/docguide/style.html#character-line-limit

[bandali]

Hi,

@didrocks:

No worry!

Minor nit: I'm actually proposing ~70 characters, rather than 80 :)

It’s even worse ! :p

Also, the issue is that by having this break at approximately this, some people like arbitrarely break before some prefix, with the article, pre or post… Markdown supports long lines and self breaking in the renderer, editor can autowrap lines visually some lines from us, so there is no technicaly limitations on that side, let’s maybe not impose some on us?

If ambiguity is a concern, we could make more specific recommendations, such as those set out in the Google style guide linked by Seb.

My main issue is that those guidelines should be agreed widely. For instance if I take your:

Also, if you consider the wording of the proposed guidelines, it says "try to limit lines to about 70 characters", meaning the proposed length is more of a suggestion rather a hard limit,

Right, but here, for instance, you say it’s a proposal and you change existing files to follow this proposal. So, if we don’t enforce one rule, we will end up with a mix of style per file, or within the file, or like in that case, a huge diff to review for some personal preferences.

I feel like this kind of argument could be used against making any kind of change. At some points we would have to agree to disagree. 🙂 But I'd like to point out that a diff of this size would be an exception rather than the norm: in each repo, there would only be one or a handful of a huge commits to rewrap all paragraphs, then if people generally follow the guidelines, diffs of that size won't be necessary.

Even so, with a decent diff tool, the rewrapping doesn't look so bad. Here's a screenshot from a diff in GNU Emacs:

Indeed, but most of the reviews are going to happen on Launchpad or GitHub, those don’t support the rich diff (look at the diff of this PR alone!).

Also, from an editor perspective, I really feel that the editor itself is able to self-wrap at the amount of characters you want without introducing a line break.

Unfortunately, support for soft-wrapping (visual) long lines at a given width in typical text editors is hacky at best, or nonexistent more often than not.

I’ll let other comments on their opinions, but to me, I can’t really review this one in the current state. At worst, if we go with 70 characters, I suggest that we have one change with the actual diff, and one to change the wrapping.

That's exactly why I broke this PR into two commits: the first one which adds the style guide, and the second one which pretty much only changes wrapping (plus a few trivial changes like changing fancy unicode quotes to their ASCII equivalents).

---

@tim-hm:

👍 to a style guide. I'm very much of the opinion that we should follow when there is a clear consensus. So, in my view, we should follow markdownlint for formatting (which afaik doesn't specify hard vs soft wraps). Wrt tone/tense/etc do we have a canonical style guide for writing or do we follow another style guide there?

From markdownlint: MD013 - Line length

Wrt line breaks, as with everything there are pros and cons to both! In my view docs are prose not code. Because its prose, I'll read it on various screen sizes / devices and I want the viewport properties of that device to determine line breaks (ie it should be responsive to width and even allow me to specify my own desired width in my renderer). For example in this thread, @bandali0's reply does expand/shrink correctly for me. If I have a narrow view (phone) then the line breaks are messed up and I get partial sentences on a line making it difficult to read. If I have a wide view say on a 4k monitor then it looks oddly padded.

IMO the docs we work with are written and updated like code (in a text editor), which are then processed and rendered to be read as prose, e.g. by rendering to HTML as done here on GitHub for *.md files in repos. And as Marco said, I think it's important that the 'source' of documentation be readable and workable using basic Unixy tools like less and diff and typical text editors like nano, vim, and emacs in a terminal.

Aside: the weird wrapping in my last reply here is due to the unfortunate non-standard behaviour of GitHub's markdown renderer in comments specifically; otherwise, hard-wrapped markdown is rendered correctly in other areas of GitHub.

Personally I find long lines difficult to read/track, but in that case I'd rather have the view respect the width I put my window at so I can adjust for my optimal setting.

So in sum, I'm 👎 to hard line breaks in the docs.

Per my earlier comments, rendered markdown indeed flows to fill the available width and respect your window width. The markdown sources, much like program sources, are a different story.

---

Here are two more screenshots, one from the current state of the repo (not wrapped), and the second one from what my PR proposes (hard-wrapped at 70). To me, the second screenshot is vastly more readable and easier to parse visually and mentally. Even at larger widths on a 1080p display, a 500-character line (such as those found in this repo before this PR) don't fit on a single line, and are awful to look at and read or try to diff, especially when they are part of a bullet list or another markdown struct.

The standard practice for docs (including markdown) of most free software projects I've seen is to hard-wrap docs files (to ~70-80 characters), including the docs for various GNU tools like Emacs or Bash, the docs for various GNOME tools and packages, the CommonMark spec, and even the README of the original implementation of Markdown by its inventor.

[didrocks]

Hi,

Hey,

@didrocks:

No worry!

Minor nit: I'm actually proposing ~70 characters, rather than 80 :)

It’s even worse ! :p
Also, the issue is that by having this break at approximately this, some people like arbitrarely break before some prefix, with the article, pre or post… Markdown supports long lines and self breaking in the renderer, editor can autowrap lines visually some lines from us, so there is no technicaly limitations on that side, let’s maybe not impose some on us?

If ambiguity is a concern, we could make more specific recommendations, such as those set out in the Google style guide linked by Seb.

My main issue is that those guidelines should be agreed widely. For instance if I take your:

Also, if you consider the wording of the proposed guidelines, it says "try to limit lines to about 70 characters", meaning the proposed length is more of a suggestion rather a hard limit,

Right, but here, for instance, you say it’s a proposal and you change existing files to follow this proposal. So, if we don’t enforce one rule, we will end up with a mix of style per file, or within the file, or like in that case, a huge diff to review for some personal preferences.

I feel like this kind of argument could be used against making any kind of change.

Absolutely not, the goal is to make something systemic, cohesive and undespitable. What I mean is that the decided rule needs to be enforced or not being put in place. Telling this is a approximate, recommendation or a guidance doesn’t really help in having consistency across repositories. So, basically, we need to be all in or not, whatever decision is taken. You can think of it as modern tooling for modern languages, where there is only one canonical (pun intended) way of styling your code (rustfmt, gofmt and probably a lot of others). The fact that those are built-in in tools instead of being outside of the languages helps having those exact discussions ;) Then, you can open ${any_project} and there is a 99% chance that it will follow the same style.

At some points we would have to agree to disagree. 🙂 But I'd like to point out that a diff of this size would be an exception rather than the norm: in each repo, there would only be one or a handful of a huge commits to rewrap all paragraphs, then if people generally follow the guidelines, diffs of that size won't be necessary.

Right, but introducing of a sentence or few worlds in an existing paragraph will still produce higher visual diff than it should. My main concern is this (and not this PR in particular) and the discrepancy of styles (if the changes themselves are not separated commit-wise to the rewrapping, as the second commit, see my next comment).

Even so, with a decent diff tool, the rewrapping doesn't look so bad. Here's a screenshot from a diff in GNU Emacs:

Indeed, but most of the reviews are going to happen on Launchpad or GitHub, those don’t support the rich diff (look at the diff of this PR alone!).
Also, from an editor perspective, I really feel that the editor itself is able to self-wrap at the amount of characters you want without introducing a line break.

Unfortunately, support for soft-wrapping (visual) long lines at a given width in typical text editors is hacky at best, or nonexistent more often than not.

Do we have evidence of this? (in particular on nonexistant the more often than on) vim can do it without any plugin with set wrap and I have never noticed an unwanted behaviour. vscode works well too. I don’t know about emacs configuration with the GUI application on top of it. I see that you have a screenshot, but I would be surprise if there is no mod for it. Even gnome-text-editor is capable of soft-wrapping! And on one hand you are arguing that editors should have better diffing tool by characters, and on another one, you are limited by the editor on soft wrapping, which seems to me like a more basic feature :)

I’ll let other comments on their opinions, but to me, I can’t really review this one in the current state. At worst, if we go with 70 characters, I suggest that we have one change with the actual diff, and one to change the wrapping.

That's exactly why I broke this PR into two commits: the first one which adds the style guide, and the second one which pretty much only changes wrapping (plus a few trivial changes like changing fancy unicode quotes to their ASCII equivalents).

Well, the second commit is not only about the wrapping: b58a790. There are few places where I can spot some additional changes. Those are probably limited and trivials, as you say, but the thing is that it’s so hard to review that and I can’t assert 100% from a reviewer’s perspective that this is the case. I would appreciate, if we agree with this styleguide that you create one commit with the actual change and a separate one for the wrapping, if not different PRs.

But basically, I still think that not wrapping for markdown is superior and more flexible from wrapping:

• it doesn’t introduce unecessary questions: "should I break before/after the article/vebs/adjective"…
• there is no special case for long lines due to URLs, like [sign-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits
• it doesn’t introduce unecessary diff when editing existing content
• and the most important, it let the power on the user's side (given the editor’s point on soft-wrapping support is clarified):
  • want 120 characters soft wrapping on your wide screen? Sure, here we are.
  • want 70 characters soft wrapping on your editor sitting on the side of your screen? Your pick!

By limiting by an arbitrary wide, you prevent this flexibility and degrade the experience for anyone confortable with other settings by either:

• having early wrapping compared to their editor's window size
• or even worse, having multiple wrapping in a middle of even lines (one full, then soft-wrap, then one truncated) if your editor is narrower than the imposed limit (let’s say we go with Google's 100 characters, but you and Marco still wants 70 or 80. Btw, it seems nobody agrees on the desired line length :p)

Ok, let me now be provocative. Don’t take it in the wrong way, but I want to understand exactly where you draw the line (similar to a wrapping line indicator :p) and get where you see the difference with the following use cases. You mean the main point is readability, right, so:

• do you split your comments when filing feedbacks on website? If I take all those conversations on this PR alone, it doesn’t seem that you are wrapping lines to 70 characters, why is that?

And to make my point on that one, github limit the size of autowrapping to something around 130 characters. Even, the notion of amount of characters for non monospace fonts is skewed: a average (if this exist) line is ~130 characters here, but if I feed with only "a" with the ubuntu font, I end up with 101 characters only). However, if I want to resize this window, I can still read the text with logical package without additional wrapping in middle of lines.

• closer to prose/documentation: do you split your lines explicitely on Google Doc or any text editor?

• do you see yourself splitting lines in emails, or IRC/MM chats? Mattermost doesn’t seem to split at any width in particular apart from your window’s size.

With those 3 use cases, I want to understand exactly why you would break in some cases and not in others. This is where I’m struggling to understand the proposal for 70 characters imposed limit. :)

So again, as you probably feel, I’m really not a fan of enforcing wrapping on markdown files. I feel we are imposing technical limitations (which are not really valid anymore but I’m happy to be proven wrong) for degrading the experience and introduce bias/inconsistency in our projects.

However, as Tim says 👍 to a style guide (hopefully on the tone/tense, our technical writers are or at least should be the stackholders on that one and we shouldn’t diverge from their advice). I don’t think we should take though past practices as a standard for setting our guidelines, or do you mean that Google's choice to split at 100 characters is wrong? If this is the case and we don’t evolve them, we would still write no tests, use autotools or so… :)

Ammendum:

That doesn't prevent to style to do some enhancements in the current lines to make it more readable (contrary to Marco, here, I can do this and the - are really readable:

However, as you did in the mixt commits we can have line breaks between items of an unordered list which makes it readable (and part of the screenshot that Marco was complaining about I think). I’m less sure about the ordered list, because you had to replace automated ordering 1., 1., 1. with 1., 2., 3.. So everytime you introduce a new items, you have to reorder them all. Maybe some markdown extension supported on popular renderer can avoid this?
I do not understand also (even if I read your other content) the 2 spaces between lines. I mean, we are diverging on purpose from english standard to introduce 2 spaces between sentences? I feel that we will have a lot of discrepencencies between documentations.

[jibel]

Ultimately, shouldn't the style guide for documentation come from the documentation team to have a shared practice across Canonical?
Did you survey other teams and see which standard they are using so we are using something similar instead of using arbitrary rules for our team only?

[jibel]

Here are two more screenshots, one from the current state of the repo (not wrapped), and the second one from what my PR proposes (hard-wrapped at 70). To me, the second screenshot is vastly more readable and easier to parse visually and mentally. Even at larger widths on a 1080p display, a 500-character line (such as those found in this repo before this PR) don't fit on a single line, and are awful to look at and read or try to diff, especially when they are part of a bullet list or another markdown struct.

If your editor was set to do word wrapping instead of cutting words in the middle it would certainly be more legible whatever the line length is.

For instance here are 3 editors which flow the text properly in a file with lines > 80 characters

[3v1n0]

But basically, I still think that not wrapping for markdown is superior and more flexible from wrapping:

I do think the same thing, but in the other way around :-D

* it doesn’t introduce unecessary questions: "should I break before/after the article/vebs/adjective"…

In fact it doesn't you have a right vertical bar that suggest you a limit, when you're there, you break.

* it doesn’t introduce unecessary diff when editing existing content

IMHO this is the main problem of having very long lines: if you change a word or an article the diff will be just one line, but it's also very hard to pick (specially with a very basic git diff ); and while it's only one line it can be a lot of content in that diff, while if you have shorter lines you may optimize these cases.

* and the most important, it let the power on the user's side (given the editor’s point on soft-wrapping support is clarified):
  
  * want 120 characters soft wrapping on your wide screen? Sure, here we are.
  * want 70 characters soft wrapping on your editor sitting on the side of your screen? Your pick!

By limiting by an arbitrary wide, you prevent this flexibility and degrade the experience for anyone confortable with other settings by either:

I think it's the very opposite especially when it comes to markdown:

• You want to use it in the terminal or small screen? You're my guest.
• You want to use it in a wider display and you prefer use wider lines? Just render it and will be any length you want.

And while a narrow text, properly styled doesn't look bad in a wider monitor (you may just think it's not taking advantage of the space you have, but it does look nice and organized), a wrapped long-lines text with bullet points and code blocks, looks just like 💩 when not rendered.

So, to me, the winning point of a line-length-limit is that it doesn't create a big problem for those who wants longer lines, but it does make life better for others, and this is not true in the other way. So, let's say, it's just more inclusive. :)

Then, when it comes to editing it, it's very hard to me to believe that it's easier to read wide lines, unless we've very different eyes 😄.

However... I guess this is one of those things in which it's basically impossible to find a full consensus 🙄, but I appreciate that other players in the market are also suggesting the same, and most of high quality open source projects tend to do this. It can't be just a coincidence.

[3v1n0]

there is no special case for long lines due to URLs, like [sign-commits]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

Oh, you don't need that. Markdown supports hyperlinks, so you can just use a link reference and put the links at the end (as it used to happen in text emails). Probably not always worth it, but if you want to stay under a strict limit you can.

[jibel]

Also, I don't understand why writing doc in markdown should be any different from writing doc in an office suite where you really don't care about line break and let the tool handle it.
I think wrapping documentation for software projects is really a legacy of the ancient times where visual space was limited and tools weren't properly handling wrapping or other advanced text editing features.
Just let it flow and your editor do the job.

[seb128]

I think it's probably time to step back a bit from the discussion at this point, it is a polarizing topic and we clearly have a split in the team in personal preferences. It's not likely that adding more arguments (or rather repeating or rewording what was already said) is going to make anyone shift.

What about doing what @jibel suggested and check with the documentation team and other parts of Canonical if they have existing guidelines or what they are doing today?

Also do we have a sense of what are the practices in the rest of the opensource world? The gitlab and google guidelines I found hinted into using line wrapping but that's small set of example, maybe we should try to look around more on what other communities are doing?