- Correct typo in README

- Add example/bullets to headlines section in writing guide

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-01-17 11:54:39 -08:00
parent b099433b6c
commit 7f7841d40a
3 changed files with 50 additions and 14 deletions
+3 -3
View File
@@ -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**:
@@ -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 <scannable-content>`.
To mark up headings in the .rst file:
@@ -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
=========