clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-07-09 06:06:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improved the Basic contribution, Images, and Cross-reference sections.

Browse Source 
Added explicit instructions on how to contribute via GitHub, naming conventions
for all files, and explicit markup instructions for figures, links, and headings.

Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero
2017-11-30 15:28:30 -06:00
parent 1d7f1c2d14
commit 76109e7d1a
4 changed files with 165 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/reference/collaboration/documentation/basic.rst
+85 -38
View File
@@ -1,20 +1,90 @@
.. _basic:
Basic writing guide
###################
Basic contribution guide
########################
For your convenience, we have complied this list of basic rules. These rules
apply to every document, in-code comment, commit message, or note. You can
find more detailed information in our :ref:`language` or in the other
This list compiles the most common format, markup, structure, and grammar
rules for your convenience. You can find more detailed information in the
referenced sections.
* Limit line length to 78 characters. This is due to the limitations
of the review system.
.. contents::
:local:
:backlinks: entry
Format
******
* Limit line length to 78 characters. The GitHub web interface forces this
limitation for readability.
* Remove trailing white space from your documents.
* Short sentences and paragraphs. Keep sentence length down to about
20 words.
* Use short sentences and paragraphs. Keep sentence length under 20 words.
* Use only lower case letters for filenames.
* Separate multiple words in filenames using dashes.
Markup
******
* Use the appropriate :abbr:`ReST (ReStructuredText)` roles for your content.
See the `ReST primer`_ for the complete list of roles.
* Use the :abbr: role to define the first instance of an abbreviation, for
example: :abbr:\`CL (Clear Linux)\`.
* Use hash-tags to underline the file's main title.
* Use asterisks to underline the file's first level headings.
* Use equal signs to underline the file's second level of headings.
* Use dashes to underline the file's third level of headings.
* Use labels to reference documentation sections. Do not reference
sections with URLs. See :ref:`cross` for details.
* Don't use explicit URLs as links, for example https://clearlinux.org/.
* Always include descriptive link text. For example:
Visit the `Clear Linux website`_. Do not use "here", "this", or similar
references for link text.
Structure
*********
* All files must have a main title and up to three levels of headings.
Restructure the content in multiple files as needed to comply.
* Use descriptive headings.
* Follow all headings with at least one paragraph of content. There should
never be to consecutive headings.
* Separate the link and the target definition. All target definitions must be
included at the end of the file. See :ref:`cross` for details.
* Use parallelism in headings, sentences, and lists. See our
:ref:`parallelism` for details.
* Put conditional phrases first in cautions and warnings. For example:
"If you do X, then Y will occur." See our :ref:`notices` guide.
* Place figures and tables immediately after related text.
* Place code or commands immediately after the leading text in a new line,
see our :ref:`code`.
* Reference figures, code examples, and tables by number.
For example, use "Figure 1," instead of "The figure above or below". See
:ref:`cross` and :ref:`images`.
* Include at least one direct reference to any table or figure you add. See
:ref:`tables`.
Grammar
*******
* Include only one main idea in a sentence. See :ref:`simple`.
@@ -47,37 +117,14 @@ referenced sections.
* Avoid contractions. See :ref:`grammar`.
* Use parallelism in headings, sentences, and lists, see our
:ref:`parallelism` guide.
* Use articles such as 'a', 'an', and 'the' to reduce ambiguity.
* Put conditional phrases first in cautions and warnings. For example:
"If you do X, then Y will occur." See our :ref:`notices` guide.
* Limit headings to three levels. Avoid heading levels beyond H3. If you have
fourth, fifth, or sixth level headings, rewrite the information in these
sections or split the content in multiple files and sections.
* To reduce ambiguity, use articles such as 'a', 'an', and 'the'
whenever possible.
* If you abbreviate codenames, use a substitution. For example: \|CL\| is
defined in the :file:`/substitutions.rst` to be replaced by "Clear Linux".
* Place figures and tables immediately after related text.
* Place code immediately after the leading text in a new line, see our
:ref:`code`.
* Use the appropriate reference format to refer to figures, code and
tables specifically: Use "Figure X," instead of "The figure above or below"
whenever possible. See :ref:`cross` and :ref:`images`.
* Avoid inserting any table or figure without having at least one
direct reference to it in the body text. See :ref:`tables`.
Next steps
**********
Additional information
**********************
Learn more about the accepted rules of grammar, punctuation, and word use in
our :ref:`language`. If you are looking for tips on how to write shorter,
clearer, and more concise content, visit our :ref:`simple` guide.
.. _Clear Linux website: https://clearlinux.org/
.. _ReST primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
source/clear-linux/reference/collaboration/documentation/cross.rst
+3 -4
View File
@@ -86,17 +86,16 @@ This creates a link to the :ref:`target <label-of-target>` using the word
.. note::
This type of internal cross reference works across multiple files, is
independent of changes in the text of the headings and works on all
independent of changes in the text of the headings, and works on all
Sphinx builders.
External References
===================
*******************
External references or hyperlinks can be added easily with ReST. Only
hyperlinks with a separated target definition are allowed.
Explicit hyperlinks consisting entire URLs, for example,
http://sphinx-doc.org/rest.html#hyperlinks must be avoided.
Do not use explicit hyperlinks consisting entire URLs. For example, links like this one, https://clearlinux.org/ must be avoided.
Hyperlinks with a separated target definition allow us to place the URL after label. They are easier to update and independent of the text, for
example:
source/clear-linux/reference/collaboration/documentation/documentation.rst
+48 -32
View File
@@ -7,12 +7,24 @@ The |CLOSIA| documentation contribution guidelines provide detailed information
about the scope and purpose of the documentation, the accepted writing style,
and the markup used.
This guide provides rules to write :ref:`clear, concise<basic>`, and
:ref:`consistent content<structures>`. Our documentation is written using
Restructuredtext and we provide
The |CL| documentation is hosted in GitHub and welcomes community
contributions. This guide provides rules to write
:ref:`clear, concise<basic>`, and :ref:`consistent content<structures>`. Our
documentation is written using ReStructuredText and we provide
:ref:`examples, templates, and best practices<rest>` for that markup.
The |CL| technical content is written in Simple American English and our
To contribute, follow the standard `GitHub flow`_:
#. Clone the `Clear Linux documentation repository`_.
#. Create your own fork of the repository.
#. Create a branch for your contribution.
#. Add your commits.
#. Open a pull request.
#. Discuss, review, and update your contributions.
#. Once the maintainer approves, your contribution is merged and published as
part of the `documentation section`_.
The |CL| technical content is written in simple American English and our
:ref:`language` contains detailed information on that standard.
This guide includes the following sections:
@@ -44,45 +56,46 @@ email to our `mailing list`_ at: dev@lists.clearlinux.org Include the outline
of the contribution you are planning and a brief description of its intended
purpose and scope.
This style guide applies to the following technical documents:
This style guide applies to the following technical content:
* Commit messages.
* Technical presentations.
* All documents in Restructuredtext within and without the documentation
repository.
* In-code comments.
* Release notes.
* Commit messages
* Technical presentations
* All documents in ReStructuredText within and without the documentation
repository
* In-code comments
* Release notes
We are always grateful to receive content contributions and are happy to help
via our mailing list or our IRC channel, #clearlinux. If you have found a
problem with one of our documents, please file a bug report. Use our
:ref:`bug-report` to submit the bug to our mailing list.
:ref:`bug-report` to submit the bug.
Tone and audience
*****************
The tone of the |CL| documentation should be clear, concise, confident, and
courteous. We are writing to peers, so we want to be familiar. Use you, we,
and avoid the passive voice but remain professional. The writing should carry
an undertone of cordiality, respect, and cooperation.
courteous. We write for our peers and want to be familiar. Use the second
person, you or we, and active voice, we configure or you run, for example.
Remain professional in your writing and carry an undertone of cordiality,
respect, and cooperation.
Assume your audience has about the same level of technical understanding and
expertise as you had when you first started. We don't want to talk down to
our readers but do not assume the readers know everything about the subject.
Offer brief explanations or summaries of "common knowledge" where a
expertise as you did when you first started collaborating. Do not talk down to
our readers but do not assume they know everything about the subject.
Offer brief explanations or summaries of "common knowledge" if a
significant portion of readers might benefit.
All contributions must follow our :ref:`code-of-conduct`.
Methodology
***********
The :ref:`documentation` contains exceptions to other style guides. It also
This guide contains differs from other style guides. It also
contains additional material not found in those sources.
To research a style question, look for the answer in the :ref:`documentation`
first. If the question is not answered there, send your question to the
`mailing list`_ at: dev@lists.clearlinux.org. For hyphenation, spelling, or
terminology usage questions, look in the Merriam-Webster's Collegiate
Dictionary.
To research a style question, look for the answer in this guide
first. If the question is not answered here, send your question to the
`mailing list`_ at: dev@lists.clearlinux.org.
If the question is answered in the existing style guide or dictionary,
the solution is implemented and enforced as described.
@@ -101,16 +114,19 @@ following sources for guidance:
* Microsoft Press Computer Dictionary, Microsoft Press; and
* Read Me First!, Oracle Technical Publications.
These sources do not always concur on questions of style and usage; nor
do we always agree with these sources. In areas where there is
disagreement, the decisions made may be explained within the respective
section.
These sources do not always concur on questions of style and usage; nor do we
always agree with these sources. In areas where there is disagreement, the
decisions are explained in the respective section.
This guide takes precedence over all other style guides in all
cases. In cases where the guide does not address the issue at hand, the
issue must be reported to the `mailing list`_ using our :ref:`bug-report`.
This guide takes precedence over all other style guides in all cases. In
cases where the guide does not address the issue at hand, please report the
issue to the `mailing list`_ using our :ref:`bug-report`.
Use Merriam-Webster's Collegiate Dictionary to determine correct
Use the Merriam-Webster's Collegiate Dictionary to determine correct
spelling, hyphenation, and usage.
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation section: https://clearlinux.org/documentation
.. _Clear Linux documentation repository:
https://github.com/clearlinux/clear-linux-documentation
source/clear-linux/reference/collaboration/documentation/images.rst
+29 -27
View File
@@ -3,53 +3,56 @@
Images
######
Images grab the reader's attention and convey information that sometimes is
difficult to explain using words alone. Well-planned graphics reduce the
amount of text required to explain information. Non-native readers rely more
heavily on graphics than those reading in their primary language because the
graphics enhance their understanding of the text.
Images or figures grab the reader's attention and convey information that
sometimes is difficult to explain using words alone. Well-planned graphics
reduce the amount of text required to explain information. Non-native English
readers rely heavily on graphics because graphics enhance their understanding of the text.
Follow these guidelines when creating graphics for the |CLOSIA|:
* Captions. Include a caption to explain or describe what the graphic
illustrates or to use as a navigational tool when referring to the
graphic from another location. All graphics should have a caption.
* Save the image files in a :file:`figures` folder. The folder must be found
at the same level as the file containing the text.
* Use only lower case letters for image filenames.
* Separate multiple words in filenames using dashes.
* Name figures with the filename of the file they appear on and add a number
to indicate their place in the file. For example: The third figure added to
the :file:`fibers.rst` file must be named :file:`fibers-3.png`.
* Include a caption describing the figure's content and to use as a reference.
All figures must have a caption.
* Use cross-references. Refer to your graphics in the main text flow.
Create a label using the filename of the image. Use``:ref:`` to place
Create a label using the filename of the image. Use the `:ref:` role to place
the cross reference, see :ref:`cross` for more details.
* Place the graphic immediately after its reference in the text flow or as
* Place the figure immediately after its reference in the text flow or as
close as possible.
* Keep graphics simple. They should only contain the information the
* Keep figures simple. They should only contain the information the
reader needs.
* Use graphics judiciously. Don't use superfluous graphics and don't
use graphics as mere decorations; they must have purpose. You don't
* Use figures judiciously. Don't use superfluous graphics and don't
use graphics as mere decorations. They must have purpose. You don't
need to show a screenshot of every single step or window in a software
installation procedure, for example.
* Avoid volatility. Don't incorporate information into a graphic that
might change with each release, for example, product versions or
might change with each release, for example: product versions or
codename abbreviations.
* Use only approved formats. Use either PNG or JPEG bitmap files for
screenshots and SVG files for vector graphics. Graphics that do not
constitute photographs or screenshots must be provided as vector
graphics to ensure that they can be changed later on.
* Use only approved image formats. Use either PNG or JPEG bitmap files for
screenshots and SVG files for vector graphics. If a figure is not a
photograph or screenshot, please provide figure as a vector graphic to
ensure it can be changed later on.
* Save the source artwork files in a :file:`figures` folder within the folder
containing your text. The filename must be entirely in lowercase and
multiple words must be separated by dashes. Name the figures of a file with
the name of the file and the order in which they appear on said file. For
example: The third figure added to the :file:`fibers.rst` file must be
named :file:`fibers-3.png`.
Examples
********
These examples follow the guidelines and can be used used as reference.
These examples follow the guidelines and can be used as a reference.
The fiber context is represented in the diagram either as a box
containing different objects or a :ref:`symbol <fibers-1.svg>`.
@@ -82,5 +85,4 @@ these guidelines.
Figure 1: Brief caption detailing the contents of the image.
Any additional explanation, description or actions depicted in the
image.
It can encompass multiple lines.
image. It can encompass multiple lines.