From 4a26755f132646e4fc66afa94fd98f54fc7cad14 Mon Sep 17 00:00:00 2001 From: Ricky Pai Date: Mon, 5 Apr 2021 05:56:31 -0700 Subject: documentation guide - update grammar --- docs/documentation.rst | 56 +++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/documentation.rst b/docs/documentation.rst index 849008a8..7b410e95 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -4,9 +4,9 @@ Documentation ############# -As most software projects we also have a lack in documentation. We encourage -every VyOS user to help us improve our documentation. This will not only be -beneficial for you (when reading something up) but also for the whole world. +We encourage every VyOS user to help us improve our documentation as we have +a deficit like most software projects. This not only be helps you when reading, +but also everyone else. If you are willing to contribute to our documentation this is the definite guide how to do so. @@ -101,7 +101,7 @@ access to the official codebase. $ git checkout master $ git merge upstream/master -* If you want to update your fork on GitHub, too use the following: ``$ git +* If you also want to update your fork on GitHub, use the following: ``$ git push origin master`` Style Guide @@ -153,7 +153,7 @@ system numbers for the documentation: * Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF`` * Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF`` -Please don't use other public address space. +Please do not use other public address space. Line length @@ -161,32 +161,32 @@ Line length Limit all lines to a maximum of 80 characters. -Except in ``.. code-block::`` because it will use the html tag ``
``
-which have the save line format as in the rst file.
+Except in ``.. code-block::`` because it uses the html tag ``
`` and
+renders the same line format from the source rst file.
 
 
 Autolinter
 ^^^^^^^^^^
 
-Each GitHub Pull request will automatically lint against the Address space and
+Each GitHub Pull request is automatically linted to check the Address space and
 line length.
 
 Sometimes it is necessary to provide real IP Addresses like in the
-:ref:`examples`. For this please use the sphinx comment syntax
+:ref:`examples`. For this, please use the sphinx comment syntax
 ``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start.
 
 
 Custom Sphinx-doc Markup
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-When writing the documentation custom commands have been developed. Please
+Custom commands have been developed for writing the documentation. Please
 make yourself comfortable with those commands as this eases the way we
 render the documentation.
 
 cfgcmd
 """"""
 
-When documenting CLI commands use the ``.. cfgcmd::`` directive
+When documenting CLI commands, use the ``.. cfgcmd::`` directive
 for all configuration mode commands. An explanation of the described command
 should be added below this statement.
 Replace all variable contents with  or somthing similar.
@@ -201,7 +201,7 @@ descriptive way in the resulting HTML/PDF manual.
      This will configure a static ARP entry always resolving `192.0.2.100` to
      `00:53:27:de:23:aa`.
 
-For a inline configuration level command use ``:cfgcmd:``
+For a inline configuration level command, use ``:cfgcmd:``
 
 .. code-block:: none
 
@@ -210,10 +210,10 @@ For a inline configuration level command use ``:cfgcmd:``
 opcmd
 """""
 
-When documenting operational level command use the ``.. opcmd::`` directive.
+When documenting operational level commands, use the ``.. opcmd::`` directive.
 An explanation of the described command should be added below this statement.
 
-With those custom commands it will be possible to render them in a more
+With those custom commands, it is possible to render them in a more
 descriptive way in the resulting HTML/PDF manual.
 
 .. code-block:: none
@@ -222,7 +222,7 @@ descriptive way in the resulting HTML/PDF manual.
 
      Display all known ARP table entries spanning across all interfaces
 
-For a inline operational level command use ``:opcmd:``
+For a inline operational level command, use ``:opcmd:``
 
 .. code-block:: none
 
@@ -231,7 +231,7 @@ For a inline operational level command use ``:opcmd:``
 cmdinclude
 """"""""""
 
-To minimize redundancy there is a special include directive. It include a txt
+To minimize redundancy, there is a special include directive. It include a txt
 file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value
 
 .. code-block:: none
@@ -270,7 +270,7 @@ vytask
 """"""
 
 When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup
-command called ``vytask`` which automatically renders to a proper Phabricator
+command called ``vytask`` that automatically renders to a proper Phabricator
 URL. This is heavily used in the :ref:`release-notes` section.
 
 .. code-block:: none
@@ -281,7 +281,7 @@ URL. This is heavily used in the :ref:`release-notes` section.
 Page content
 ------------
 
-The documentation have 3 different types of pages, the same kind of pages must 
+The documentation has 3 different types of pages. The same kind of pages must 
 have the same structure to achieve a recognition factor.
 
 All RST files must follow the same TOC Level syntax and have to start with
@@ -307,12 +307,12 @@ For example:
 The article starts with a short intruducing about the command or the
 technologie. Please include some helpfull links or background informations.
 
-After this a optional section follows. Some commands have requirements like the
-compatible hardware (e.g. Wifi) or some commands you have to set before. For
-example it is recommended to set a route-map before configure bgp.
+An optional section follows. Some commands have requirements like compatible
+hardware (e.g. Wifi) or some commands you have to set before. For
+example, it is recommended to set a route-map before configure BGP.
 
-In the configuration part of the page all possible confiuration options
-should be documented. Use ``.. cfgcmd::`` like described above.
+In the configuration part of the page, all possible confiuration options
+should be documented. Use ``.. cfgcmd::`` described above.
 
 Related Operation command must be documented in the next part of the article.
 Use ``::opcmd..`` for these commands.
@@ -323,16 +323,16 @@ next optional part.
 Operation mode pages
 ^^^^^^^^^^^^^^^^^^^^
 
-Operation mode commands, which didn't fit in a related configuraton mode command
-must documented in this part of the documentation.
+Operation mode commands that does not fit in a related configuraton mode command
+must be documented in this part of the documentation.
 
-General concepts for troubleshooting belong here as well as detailed process
-descriptions.
+General concepts for troubleshooting, and detailed process descriptions belong
+here.
 
 Anything else
 ^^^^^^^^^^^^^
 
-Anything else what is not a configuration or a operation command have no
+Anything else that is not a configuration or an operation command have no
 predefined structure.
 
 
-- 
cgit v1.2.3