Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Add MD guidelines to Contributing Guide #18

Open
barbaricyawps opened this issue Mar 17, 2021 · 1 comment
Open

Add MD guidelines to Contributing Guide #18

barbaricyawps opened this issue Mar 17, 2021 · 1 comment
Labels
enhancement New feature or request

Comments

@barbaricyawps
Copy link
Contributor

In a Slack convo, @bwklein recommends:

Hard-wrapped Markdown is my least favorite kind of Markdown. One sentence per line, and soft-wrap in your editor if you need to.

That sounds like a pretty reasonable approach and an easy rule of thumb to apply. We should consider adding it to our Contributor Guide or an MD guide (if we feel we need a separate guide).

@barbaricyawps barbaricyawps added the enhancement New feature or request label Mar 17, 2021
@bwklein
Copy link
Member

bwklein commented Mar 17, 2021

Some notes:
https://vanemden.wordpress.com/2009/01/01/ventilated-prose/
https://rhodesmill.org/brandon/2012/one-sentence-per-line/
https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

Most text editors have soft wrap capabilities now, so an 80 char limits is less useful and can make using ventilated prose and version control unnecessarily complex. (lots of reflowing paragraphs to make it fit the mold.)
Ventilated prose is also great for version control diffs and translations, where sentences are their own 'chunk' based on line breaks.

Comment from Ian: https://thegooddocs.slack.com/team/U01AYHSAAMV
As a final note, we use linters in the following way and this works well for us:

  • Vale for language style linting (with a bunch of custom rules)
  • markdownlint for linting only Markdown style

https://github.com/DavidAnson/markdownlint-cli2 allows for custom rules.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants