Docs Style Guide
joel at rtems.org
Thu Jul 18 18:33:27 UTC 2019
On Thu, Jul 18, 2019, 12:35 PM Chris Johns <chrisj at rtems.org> 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 .
> Thank you for raising this.
> > We should start to collect Documentation Style notes in a wiki page,
> > and then push it to the docs . 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.
> 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
> and other times an edit to cut the length down does not remove any
> 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.
> > 
> That looks like a good spot to put a guideline.
It should be in the SW Engineering Handbook. Is that what that url matches?
> devel mailing list
> devel at rtems.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the devel