From 76109e7d1ade92acef59349d90de7ca35c39ad23 Mon Sep 17 00:00:00 2001 From: Rodrigo Caballero Date: Thu, 30 Nov 2017 15:28:30 -0600 Subject: [PATCH] Improved the Basic contribution, Images, and Cross-reference sections. 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 --- .../collaboration/documentation/basic.rst | 123 ++++++++++++------ .../collaboration/documentation/cross.rst | 7 +- .../documentation/documentation.rst | 80 +++++++----- .../collaboration/documentation/images.rst | 56 ++++---- 4 files changed, 165 insertions(+), 101 deletions(-) diff --git a/source/clear-linux/reference/collaboration/documentation/basic.rst b/source/clear-linux/reference/collaboration/documentation/basic.rst index ad7e495b..d8b6860a 100644 --- a/source/clear-linux/reference/collaboration/documentation/basic.rst +++ b/source/clear-linux/reference/collaboration/documentation/basic.rst @@ -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 diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst index 96102ed1..e3b5f975 100644 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -86,17 +86,16 @@ This creates a link to the :ref:`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: diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst index ce877e94..df83ef8a 100644 --- a/source/clear-linux/reference/collaboration/documentation/documentation.rst +++ b/source/clear-linux/reference/collaboration/documentation/documentation.rst @@ -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`, and -:ref:`consistent content`. 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`, and :ref:`consistent content`. Our +documentation is written using ReStructuredText and we provide :ref:`examples, templates, and best practices` 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 diff --git a/source/clear-linux/reference/collaboration/documentation/images.rst b/source/clear-linux/reference/collaboration/documentation/images.rst index 264f8892..ee46e817 100644 --- a/source/clear-linux/reference/collaboration/documentation/images.rst +++ b/source/clear-linux/reference/collaboration/documentation/images.rst @@ -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 `. @@ -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.