Docs Style Guide

Chris Johns chrisj at rtems.org
Thu Jul 18 17:35:39 UTC 2019


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



More information about the devel mailing list
https://lists.rtems.org/pipermail/devel/2019-July/054559.html
lists.rtems.org
CC-MAIN-2023-50
4590
application/http; msgtype=response
sha1:AD5SQEVBNIZ3FVQJWC634CHSPTYMX5WQ
<urn:uuid:b775960a-b6cf-46dc-aefa-6b7590900143>
2023-11-28T22:16:05Z
140.211.10.142
text/html
sha1:VSVCW4YTBEC36KYBQFGPUQ25I2G63KZZ
<urn:uuid:2ac61681-62bb-4300-8b2c-41456c9cdb32>
https://lists.rtems.org/pipermail/devel/2019-July/054559.html
response
<urn:uuid:c0f68d3f-391e-4f34-a2e2-102dc3f86913>
isPartOf: CC-MAIN-2023-50
publisher: Common Crawl
description: Wide crawl of the web for November/December 2023
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-156
software: Apache Nutch 1.19 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.5-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/