Docs Style Guide

Joel Sherrill joel at
Thu Jul 18 18:33:27 UTC 2019

On Thu, Jul 18, 2019, 12:35 PM Chris Johns <chrisj at> wrote:

> 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
> > 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]
> >
> That looks like a good spot to put a guideline.

It should be in the SW Engineering Handbook. Is that what that url matches?

> Chris
> _______________________________________________
> devel mailing list
> devel at
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the devel mailing list