Docs Style Guide

[Chris Johns]

On 19/7/19 1:32 am, Gedare Bloom wrote:
> Reviewing the BB doc patch, I realized that we need a style guide for
> writing docs [1].

Thank you for raising this.

> We should start to collect Documentation Style notes in a wiki page,
> and then push it to the docs [1]. If anyone has some initial set of
> thoughts, it would be good to put them down in reply to this email.

We do have https://git.rtems.org/rtems-docs/tree/README.txt#n393.

> My initial question on the BB patch is whether to incorporate the 80
> char line limit or not.

Rules to line wrap at 80 characters are subtle and not straight forward. The
patch highlights the issue as the long lines appear to me to be copies of
terminal output. I suspect we need to consider these on a case by case basis to
weigh up the effect of the long line in the final output vs keeping what is
present as close to what a user sees. Sometimes you may want the exact output
and other times an edit to cut the length down does not remove any important
information. Another factor is the HTML output keeps long code style lines as a
single line you can scroll and PDF wraps the lines. The wrapping in PDF is
choice I made to make sure all the text is present and within a page.

Amar and I had many long discussions on this specific issue when I migrated the
documentation to Sphinx.

> 
> [1] https://docs.rtems.org/branches/master/eng/users-manuals.html#documentation-style-guidelines
> 

That looks like a good spot to put a guideline.

Chris