Skip to content

Resolve "Add Notes about Doc Format to Contribution Guide"

Frederik Beaujean requested to merge frederik.beaujean/AutowareAuto:517-doc-format-notes into master

Description

I add a separate file with a proposal for documentation guidelines based on my past experience and internal guidelines.

closes #517 (closed)

Notes for Reviewer

One issue I'm not decided on, so the MR is not entirely finished. One of the issue comments #517 (comment 390566005) says:

The primary item is "Each sentence should be on a new line which helps with reviews."

and I incorporated that. But this is in conflict with the other new guideline:

Lines in markdown shall in general be limited to 100 characters

When editing the markdown file, it is easy to set a column limit and fill/reflow the paragraph automatically. But then the one-sentence-per-line rule is usually violated. In my opinion, the side-by-side diff in gitlab or your favorite editor is powerful enough so sentences don't have to be on separate lines. This would save everyone from manually fiddling with line breaks, which I consider a waste of time these days.

Checklist

  • Documentation was updated

Merge request reports