Exploring Guidelines for Line Length and Newline in Markdown Documentation.

[hochan222]

We're setting guidelines for the maximum number of words per line in Markdown files within the ko-locale. We would like to write a guide related to it.

I'm keen to learn if there will be a guideline for the single-line character limit in Markdown files across the entire content repo (or translated-content repo). (If possible) If such a guideline exists, could you specify the document where it's mentioned?

As shown below, in the content repo, documents have recently(..?) been written divided into multiple lines rather than single lines, so I asked if there was a related direction. I think there was a direction before that recommended writing in 80 characters or less, but I couldn't find it when I looked for it.

• https://github.com/mdn/content/blob/27b116a3801c7e718e9c68f578e89da2bd87fff2/files/en-us/web/javascript/reference/global_objects/symbol/keyfor/index.md?plain=1#L10

Thank you all. 🙇🙇

---

I start a GitHub discussion to track the conversation in the PR below.

• [ko] DataView.prototype.setUint8() 추가 translated-content#18751 (comment)

[hochan222]

Brian wrote:

Heya 👋🏻 - we can start a GitHub discussion to track this in case the conversation is lost in this PR, if you like.

As far as character limit goes, I am not aware of any guideline that says you should use max X chars per line.

I think there was a direction before that recommended writing in 80 characters or less

You can definitely find some existing docs where this was a preferred authoring style by some writers, but I have not seen any new documentation added at all that uses 80 char limit. In fact, if this was a requirement, it would probably be enforced with linting / code style tools.

We do have one guideline about whitespace which says

Don't unnecessarily add or remove line breaks on pages that follow a certain formatting style.

So if a page uses 80 chars limit for a lot of text, don't make whitespace-only changes to change the style.

edit: for illustration, when making EN changes, it wouldn't be a good practice to do this:

+ This is a new piece of content and the purpose of the pull request

- Don't unnecessarily add or remove line breaks 
- on pages that follow a certain formatting style.
+ Don't unnecessarily add or remove line breaks on pages that follow a certain formatting style.

---

This is what @bsmth responded to. Thank you 🙇🙇

• [ko] DataView.prototype.setUint8() 추가 translated-content#18751 (comment)

[hochan222]

@1ilsang, @wisedog It would be good to continue the conversation here.

I think I need some time to think. Please leave a comment.

cc. @mdn/yari-content-ko

[1ilsang]

I know you've made efforts to track changes to content pages, such as introducing 'sourceCommit'.

I see this discussion as an extension of that. Matching the line count to the original content is expected to be convenient from a holistic perspective of document management.

Therefore, I think it would be a good idea for translated documentation to follow the original line count.

If you have any other thoughts, feel free to let me know!

Thank you!

[swimjiy]

I also looked to if there was any related direction, but I could only find issues with lint, as shown below, and most of them seemed to be negative😅.

mdn/content#6936
https://github.com/orgs/mdn/discussions/211#discussioncomment-3482149

[wbamberg]

When we originally migrated to Markdown, a lot of people were strongly against having hard-wrapping enforced by Markdown, which is why we don't set the relevant Prettier option.

[hochan222]

[yari-content-ko team meeting]

The team meeting concluded the following:

• Follows the format of the content repo first.
  • Contributors are guided in the direction of maintaining the number of lines without any special standards for dividing lines.
• Do not force a line break outside of the format.
  • In case of long text, it is better to keep the number of lines the same as the original text for diff comparison.

---

@wbamberg Thank you for your comment.

Is it okay to write a PR that modifies the 10 lines in the content repo document below as a single line without a newline?
It would be good to maintain a consistent document format across the content repo.

• https://github.com/mdn/content/blob/c40fe6508ac4add549d315aa20f6bc2fca49c27e/files/en-us/web/javascript/reference/global_objects/symbol/keyfor/index.md?plain=1#L10

[wbamberg]

@hochan222 yes, I think this is fine. As far as I know where we are with this is:

• many (most?) people would like to avoid breaking in the middle of a sentence
• our current docs are inconsistent: as in the example you gave, some pages break in the middle of a sentence sometimes and not other times, even within the same page
• we don't really want to reformat everything to be consistent, because it would be a huge amount of churn
• sometimes people fix formatting issues like this when they are making a PR to the file anyway (for example, if they are fixing a bug they might reformat the file at the same time). I know for instance @hamishwillee does this. And I think this is fine.

[hamishwillee]

I tend to use sentence breaks, because I find it helpful for parsing the content as I review it, and because it makes it easier to spot changes in github diff than a whole paragraph between line breaks.

But I don't advocate for any line break format other than "not midway through a sentence". I am strongly opposed to line breaks based on character length.

Note that markdown line breaks make absolutely no difference to the rendered content. It may make some difference to translation tooling (historically at least, some tools consider line breaks to be the semantic break point for string translations, which is unhelpful).