From d8e9f815d2d3f7c6d6b5961b1e01b9444af7afec Mon Sep 17 00:00:00 2001 From: "L.S. Cook" Date: Fri, 9 Oct 2015 15:53:43 -0700 Subject: [PATCH] doc: Adding some parallelism to the documentation.rst scope summary Deleting some redundant references. Change-Id: I5187a88232297a9bd57fec9025b4bd80d7371aea Signed-off-by: L.S. Cook --- .../documentation/documentation.rst | 40 +++++++++---------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/doc/collaboration/documentation/documentation.rst b/doc/collaboration/documentation/documentation.rst index 44f7c51c43b..40ead2de61b 100644 --- a/doc/collaboration/documentation/documentation.rst +++ b/doc/collaboration/documentation/documentation.rst @@ -1,16 +1,15 @@ .. _documentation: -Zephyr Project Documentation Style Guide -######################################## +Documentation Style Guide +########################## -The Zephyr Project Documentation Style Guide is a document -produced and maintained by the |project|. This chapter provides -overview information about the scope and purpose of this manual, along -with related resources. +This Documentation Style Guide is produced and maintained +by the |project|. This section provides overview information about the +scope and purpose of this manual and links to related resources. -This section addresses writing styles. It provides a rules for writing -clear, concise and consistent content. It is written using -Restructuredtext and contains all the use cases for that markup. +These guidelines help you write in a manner that is clear, concise, and +consistent. Written using :abbr:`ReST (ReStructuredText)`, it also contains +various use cases for that markup. Scope ***** @@ -19,33 +18,32 @@ This guide includes the following: :ref:`basic_writing` -Covers the basic issues of writing styles, including general writing +Covers expected writing styles for the project, both general writing guidelines and specific guidelines for step-by-step procedures. :ref:`detailed` -Offers specific examples of all guidelines included in the -:ref:`basic_writing`. Additionally, it contains the guidelines for -module-based writing. +Offers specific examples of guidelines included in the :ref:`basic_writing`. +Additionally, it outlines the standards for module-based writing. :ref:`language` -All the spelling, usage, grammar, mechanics, punctuation, -capitalization, and various rules about writing technical documents. +Discusses important usage rules to be aware of regarding grammar, mechanics, +punctuation, capitalization, abbreviations and other rules to be aware of +when authoring and contributing technical content. :ref:`restructured` -Specifically addresses writing standards and syntax with regard to -Restructuredtext. +Addresses specific writing standards and syntax pertaining to ReST. :ref:`about_docs_style` -Contains all the information regarding the guidelines above including the references used, the -intended audience and the methodology employed. +Contains information regarding the guidelines above including references, +intended audience, and the methodology employed. This reference manual is written in American English. -Keep in mind that this style guide applies to the following technical documents: +Keep in mind that this style guide applies to the following: * Commit messages. @@ -60,7 +58,7 @@ Keep in mind that this style guide applies to the following technical documents: Related Guidelines ****************** -These related guidelines include information that might prove useful to +These related guidelines include information that may also prove useful to developers: * :ref:`gerrit`