Docs Style Guide

[Joel Sherrill]

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 [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.
>

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

>
> Chris
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190718/71836c4c/attachment-0002.html>