diff --git a/README.rst b/README.rst index 6568f681..ab37040d 100644 --- a/README.rst +++ b/README.rst @@ -4,8 +4,8 @@ Documentation build instructions .. todo add comment re not using standards here. `Clear Linux\* OS documentation`_ is written using `reStructuredText`_ and -built using `Sphinx`_. Documentation may be built locally for development and -testing purposes by following the instructions in this README. +built using `Sphinx`_. Follow the instructions in this README to build the +documentation locally for development and testing. Please make yourself familiar with our `contribution guidelines`_ before submitting a contribution. @@ -32,7 +32,7 @@ local machine. Run the build ************* -We build our documentation using . In the source directory of your +We build our documentation using Sphinx. In the source directory of your local clear-linux-documentation repository, build the documentation by running **make html**: diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst index 7cd9910b..811ee4dd 100644 --- a/source/clear-linux/reference/collaboration/structure-formatting.rst +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -102,12 +102,12 @@ Use headings to section and organize your content for better readability and clarity. * All files must have a top level heading, which is the title for the page. -* Headings should be short and descriptive. -* Write headings in sentence case (capitalize only the first word and proper - nouns). * Up to three additional levels of headings are allowed under the title heading. -* Each heading must be followed by at least one paragraph of content. There - should never be two consecutive headings. +* Each heading should be followed by at least one paragraph of content. Avoid + two or more consecutive headings. + +Refer to the :ref:`writing-guide` for tips on using headings to create +:ref:`scannable content `. To mark up headings in the .rst file: diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst index 04d1fe30..8f307b2a 100644 --- a/source/clear-linux/reference/collaboration/writing-guide.rst +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -79,22 +79,58 @@ concise and scannable. Avoid using the product name in page titles and headings. +.. _scannable-content: + Make content scannable ********************** Organize your content to make it scannable for the reader, which helps them find -what they need quickly, and helps them understand more efficiently. +what they need quickly, and to understand the information more efficiently. * **Put the most important content first.** Make sure your introduction clearly - communicates what the reader can find on the page. Organize supporting - information towards the end of the page. -* **Write scannable headings.** Think of headings as the outline for your - content. Write headings that are short, specific, and use `Parallelism`_. - Top level headings should show the most important subjects on the page. + communicates what the reader can find on the page. Present the point of the + document first, and organize supporting information towards the end of the + page. +* **Write scannable headings.** Expect readers of documentation to skim and scan + the content, and to leave if they dont find what they need quickly. Good + headings add organization to your content and help the reader to find and + understand content more effectively. Follow our guidelines for writing + effective `Headings`_. * **Write great link text.** Great link text tells the reader what they can expect when they click on a link. It also helps make the page more scannable. Follow our guidelines for writing `Link text`_. +Headings +======== + +Use these guidelines to write effective headings: + +* **Be concise and descriptive.** Use only the words necessary to describe the + section. +* **Use sentence case.** Capitalize only the first word and proper nouns in a + heading. +* **Avoid punctuation.** Unless your heading is a question, don't use sentence + punctuation in headings. +* **Use parallel structure.** Headings at the same level should use the same + grammatical pattern. This provides structure to the document and helps users + find information more easily. See :ref:`parallelism`. +* **Use strong verbs.** Strong, active verbs get to the point. Avoid -ing verbs, + such as *Running*, *Testing*, etc. + +For example, two headings at the same level: + +**Use this:** :: + + Install software + + Configure software + +**Not this:** :: + + Installing the Software on the Platform + + Software Configuration. + Link text =========