Do not wrap text

Using newlines to wrap text at 80 characters without starting new sentences on a new line makes it harder to change the text and should be avoided.

If you need to insert or remove text into a paragraph that is formatted like described above you either:

1. Have to make one sentence awkwardly long or short.
2. Need to rewrap the text, this can't be done in some editors (GitLab online editor being one) and will cause every line to show up in the diff.

As an alternative you can not use new lines to wrap text or you can wrap using new lines and start new sentences on a new line.

Example of text formatted like this: https://gitlab.com/gitlab-org/omnibus-gitlab/commit/e95de8b9e34b6dddf8b8df8f230d9af5db02853a

Subscriber only example of problems when changing: https://gitlab.com/subscribers/gitlab-ee/commit/044036e49864188711f73c47404d439edfca5c49

@jacobvosmaer what do you think?

Sytse Sijbrandij @sytse wrote on Mon, 17 Aug 2015 23:42:09 UTC :

@jacobvosmaer Also, even when you rewrap with your editor the diff will become very messy, making it hard to see what changed https://dev.gitlab.org/gitlab/gitlab-ee/merge_requests/479/diffs

Drew Blessing @drew wrote on Tue, 13 Oct 2015 16:00:47 UTC :

I'm slightly confused on both of your positions after reading this discussion

Our PROCESS.md is a great example where not wrapping the paragraphs makes it an utter nightmare to edit. Open that file in RubyMine or something and it just scrolls horizontally forever. The main tenant of markdown is that even the source is easy to read/write. Periodic line breaks strengthen this readability IMO.

Jacob Vosmaer @jacobvosmaer wrote on Tue, 20 Oct 2015 13:59:38 UTC :

@drew like you I am in favor of having fixed-width markdown files that are readable in the terminal.

Jacob Vosmaer @jacobvosmaer wrote on Tue, 21 Jul 2015 11:55:30 UTC :

Using one line per sentence is hard to read. Nobody would publish text as one sentence per line. The only reason you can get away with 'one line per sentence' in markdown is because most readers see it after conversion to HTML, and HTML rendering ignores the newlines.

I do not write text in a WYSIWIG editor (e.g. Word, Google Docs) but in editors designed for text where newlines matter (e.g. Vim, Sublime). Because of that I cannot rely on the crutches of HTML removing the offending newlines for me.

Text that is stored as one line per sentence is hard to read and therefore hard to edit. I think that is objectively bad.

If you need to insert or remove text into a paragraph that is formatted like described above you either: (1) Have to make one sentence awkwardly long or short.

This is a false option. Nobody in their right mind would do this. We are not talking about 'git commit line golf' here.

(2) Need to rewrap the text, this can't be done in some editors (GitLab online editor being one)

Too bad? The rest of the file should still read OK.

By the way, reformatting in the online editor would be useful in itself to create nicer merge commit messages in merge requests.

and will cause every line to show up in the diff.

I am not sure if that is a problem. You are making a large change in a paragraph, so as a reviewer I would like to read the paragraph before and after, not just the line. So I would not mind then that the paragraph registers as 'changed' in the diff.

Sytse Sijbrandij @sytse wrote on Tue, 21 Jul 2015 14:16:20 UTC :

@jacobvosmaer With 'Too bad', do you mean you expect the user to rewrap by hand? I did option 1 from time to time, hope you still think I'm in my right mind.

Jacob Vosmaer @jacobvosmaer wrote on Tue, 21 Jul 2015 14:27:11 UTC :

@sytse I meant 'too bad if text-editor readability is locally damaged by an edit'.

Sorry to disqualify your option 1 so harshly. But changing what you write just to make the 'git diff' nicer seems like a unneeded constraint on your communication to me.

Sytse Sijbrandij @sytse wrote on Tue, 21 Jul 2015 15:06:08 UTC :

@jacobvosmaer It is not the git diff that becomes nicer, it is that a ragged right side edge in the HEAD version looks like something went wrong.

mentioned in issue www-gitlab-com#538 (closed)

Should go into the Blog post style guide in the handbook https://gitlab.com/gitlab-com/www-gitlab-com/issues/538

Closing this in favour of that.

Status changed to closed

@nearlythere This subject is controversial. If we write this blog post it should have the two opinions (to wrap and to now wrap) represented. I don't think this is ready for the style guide unless we discard my opinion (which is an option).

Status changed to reopened

@sytse I wasn't aware this was still under consideration. Sorry for closing. Do you think we should give writers the option of not hard-wrapping?

For blog post technical articles we will follow the documentation style guide. The blog post style guide is an override or addendum to that. The consensus there is that the broken lines facilitate review.

Considering the numbers of reviewers on technical articles written by guest writers, I would think we should follow their lead.

@sytses oh!! You said "if we write this blog post" -- I didn't consider this a blog post idea but actually ideas for the Blog Post Style Guide. Am I confused? Probably.

For reference, here is the current blog style guide

https://gitlab.com/gitlab-com/blog-posts/blob/master/STYLEGUIDE.md

Added CEO interview label

we recorded this

Added Guest Posts label

Added Ghost Posts and removed Guest Posts labels

@marcia this is in our content que: https://docs.google.com/document/d/1cCCQgeaW9Q4d3fs1AraFjliJuBYaEmlXKyTBfE6SM0M/edit

Can/should we publish this?

Yes @Lindberg, definitely! :D

Reassigned to @eReGeBe

Reassigned to @Lindberg

@marcia I'm going to add this to markdown and create merge request so we can publish next week.

Mentioned in merge request www-gitlab-com!3399 (merged)

Status changed to closed by merge request www-gitlab-com!3399 (merged)

Mentioned in commit virtuacreative/www-gitlab-com@bfd71142