A couple of days ago, we had a problem with the Handbook, where the navigation items on the left weren’t being displayed properly. It turned out the updated Mkdocs requires a clean markdown file with some strict header rules that need to be watched.
Accordingly, we added a markdown linter to the handbook. Kudos to @Fox and @kahlil for reviewing those changes.
When reviewing the changes, there were conflicting discussions regarding the history that would be destroyed if certain errors where fixed, which are:
MD004/ul-style - Unordered list style
MD005/list-indent - Inconsistent indentation for list items at the same level
MD007/ul-indent - Unordered list indentation
MD013/line-length - Line length
Therefore, instead of addressing those quality errors, we ended up silencing them.
For efficiency when making changes that require changing several files in quick succession (tracing, debugging, changes across multiple components, etc.). The more code that one can fit on the screen, the less context switching between files. It has always seemed silly to me that we have widescreen monitors but we usually don’t make good use of all that realestate.
@nizar@adolfo@swalladge Another reason I have for 80 is that my IDE creates a preview pane that live renders what I’m doing, so my three columns are the project listing, the code, and the preview render.
I can kind of squish things to make 120 fit, though, so my preference for 80 is slight.
I mean a lot of newer projects go for slightly wider than 80 characters (black the python formatter defaults to 88 chars, and I’ve seen 100 in several places). 120 is starting to get too long though. How about we compromise on middle ground - 100 characters?
I’ve commented on the PR already, but I don’t see the point of enforcing line length for text. Code ok, but this is a text file. Also don’t forget that this is meant to be edited by non-technical people - we should not be adding code-like linting to the handbook.
When you enforce a line length for prose (paragraphs of text) and then insert even a single word in the middle of the paragraph, it can generate a very ugly diff because you need to go through and modify the spacing of every single subsequent line to get it fixed:
the quick brown |
fox jumped over |
the lazy dog |
After adding a single word (“sudo”):
the quick brown |
-fox jumped over |
-the lazy dog |
+ fox SUDO jumped|
+ over the lazy |
+ dog |
Literally everyone’s text editor is capable of soft wrapping the text at whatever width is perfect for their display, and it will always look best and have the cleanest diffs if you just use lines without any length limit and let the editor wrap them as needed based on where they’re being displayed.
So while I like most of these changes I personally don’t like line length limits for docs.
I agree that this is a problem if enforced in this way. However, the opposite problem is when entire paragraphs are on a single line, which is not nice even with soft wrapping. Git diffs are arguably just as bad because the entire paragraph has still changed. (except smart highlighting can point out the changes within the line usually).
May I introduce you to the idea of semantic line breaks. This is when you enter a line break where one would naturally pause anyway: at the end of sentences, after commas in long sentences, etc. Unfortunately some markdown processors treat these as hard breaks for some reason, but in most cases it’s the best of both worlds. Line lengths are manageable and diffs are informative.
But then you lose the usefulness of many linewise operators in some editors, and shorter semantically wrapped lines always look better than softwrapped lines. Plaintext is meant to be nicely manually formatted, not munged into one line.
Every tool I use has this smart highlighting, which is why I don’t see this as a problem.
Interesting, but I personally find this to be the “worst of both worlds.” I would prefer either other option.
I guess for Markdown my assumptions are different - I think of the plaintext formatting only as a convenience for the author and I assume that all readers are using a rendered version. Plus when I author I usually have a live preview of the rendered version open, so I find that soft wrapping is easy to work with and consistent with the final result:
However, I will grant that if you think of the plaintext version as the “final form” that people are consuming and authoring with, there is a strong case for line wraps. I don’t want to impose my opinion on the team here, but based on how I work I definitely prefer soft wraps.
That’s true, different workflows and different assumptions. For context, I never view the rendered output of a markdown document, unless in contains something mangled like a huge unaligned table or html escape codes. I take the view that markdown is a light markup syntax that is meant to be just as useful to consume in plain text as the rendered output (eg. I don’t see much difference in usability between a line prefixed with ## and a line in a larger font size). To quote John Gruber himself:
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
Curious though, what difference would it make to you if you always view a live preview of the rendered output?
Not every tool I use has it, so it is a problem often for me.
To repeat something that I mentioned previously – remember that the handbook, and the rest of our non-technical documentation, need to remain simple to edit by non-technical team members. Adding constraints on the length of lines and requiring the use of specific line-wrapping in editors would add to an already pretty long list of non-intuitive requirements. We need to make it easier for non-technical users to participate in the team’s activities, not harder.
I’m generally on @swalladge’s side of the debate, as I mostly write and consume markdown in its source format. Plus, I’m a vimmer, and vim doesn’t do arbitrary soft wrapping (one has to resize the window, which as a full-screener I’m loathe to do), so long lines are a bit of an eyesore.
I can’t say I like the proposed semantic breaks as an alternative, though. They’re too much of a departure from paragraphs, for me.
@antoviaque has a good point, though. I figure it’s part of our collective job description as open source folk to be highly adaptable to different text formatting standards. So I can work with whatever’s best for the intended audience that is least adaptable - which I’m guessing is unlimited line lengths.
(It’s too bad the non-technical world went that direction, though. I’m an RFC 822, 72 column person at heart, so between unlimited lines and 80 chars, I’ll pick 80 chars any time.)