mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
- 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:
+3
-3
@@ -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
|
||||
=========
|
||||
|
||||
|
||||
Reference in New Issue
Block a user