Changes between Version 5 and Version 6 of How to document the quickstart file

Timestamp:

18 Nov 2019, 20:04:21 (4 years ago)

Author:

flicstar

Comment:

Major updates based on my work as part of the Google Season of Docs 2019.

How to document the quickstart file

@@ -3 +3 @@
 = How to document the quickstart file
 
-== Where to find the quickstart files
-
-The quickstart files are located at:
+== What is the quickstart?
+The Quickstart is designed for a new user to run through a specific scenario. It uses numbered steps with screen shots to create a procedure to demonstrate one or more of the application's core functions. It should be able to be completed in 5 to 10 minutes, and will leave the user with an understanding of how to launch the application and get a feel for what it can do.
+
+
+== Where to find the quickstarts
+
+The quickstarts are located at:
 
 https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
 
-== Notation
-
-For this documentation:
+
+== Data for sample procedures
+In order to reduce disk space and maintain consistency between applications, all Quickstarts should make use of the common #Example_Datasets that are loaded with OSGeoLive. If the datasets don't cover your requirements, discuss this with us and we may add another suitable common dataset.
+
+== How to write a quickstart
+
+Write in a friendly, conversational style similar to the way a teacher would talk a class through an example. The QuickStarts for R and GeoServer do this very well.
+
+
+=== Notes about markup
+
+Source documentation is written in RST wiki format and is built using sphinx. Docutils provides a good reference for writing in RST format [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]
+
+Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items. 
+
+**Section headings**
+Use 80 characters above and below the quickstart title - you need 80 because the title uses a slug and we don't know how many characters the application name is.
+All other section headings characters need only be as long as the heading.
+
+**Basics**
+
+* This is a bulleted list.
+* It has two items, the second
+  item uses two lines. (note the indentation)
+
+1. This is a numbered list.
+2. It has two items too.
+3. This numbered list
+
+   * Has a bullet list (note the blank line and the indentation)
+   * This bullet has an image (note the blank line and the indentation)
+
+      .. image:: /images/projects/<slug>/image_name.png
+         :scale: 70 %
+
+
+The following is for a code block
+
+::
+
+   Code starts here, (note the blank line between the `::` and the code
+   More code
+
+This is not code
+
+
+The following is `link title <http://this/is/the/external_link.html>`__
+(note back ticks ` and the 2 underscores at the end)
+
+The following is an internal link :doc:`../overview/<other_slug>_overview`.
+
+
+=== Notation explained
 
 *  Words surrounded by `< >` are to be defined by the person documenting the project
@@ -30 +84 @@
 Most of those variable points to data collected into a file called `projects_info.csv` that you can find at the root of the documentation folder: [https://github.com/OSGeo/OSGeoLive-doc/blob/b1d9cce02535fd75e9b891ebaea379103ab831bb/projects_info.csv ]
 
-It can be a good idea to fill this file first before writing the quickstart page. How to fill `projects_info.csv` is explained here : https://trac.osgeo.org/osgeolive/wiki/How%20to%20configure%20a%20project%20documentation
-
-
-
-= `quickstart_<slug>.rst` File Structure
+
+It can be a good idea to fill the projects_info.csv file first before writing your quickstart. How to fill `projects_info.csv` is explained here : https://trac.osgeo.org/osgeolive/wiki/How%20to%20configure%20a%20project%20documentation
+
+
+=== Writing tips
+
+**Overview section**
+
+This section is required and has no heading. Start with a sentence describing what the application is and does. 
+Next, describe what will be covered in the Quick Start. Choose a few features to show. If you're showing one or two things, write that in sentence format. If it's three or more, use a bullet list.
+Mention any prerequisites that are required to complete the Quickstart, for example, internet connection or data to test with.
+
+**Contents list**
+
+Use headings in your document to automatically generate a table of contents. The headings should start with verbs, and should be the same or similar to what you have said the Quickstart will cover.
+
+**Main body of the quickstart**
+
+Use headings to create sections and structure in the quickstart. The heading title for the first section is "Start application name". 
+Use numbered steps to describe what to do. Steps start with a verb or action word. Include only one action per step. A description of the expected result is not a new step.
+Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style
+
+For images, use a scale of 50% from a 1024x768 display (preferred) or 70% from a 800x600 display. Markup the graphic with red circles to highlight any particular areas of note on the GUI (if required). Store images here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/images/projects/1024x768/
+
+Notes are optional. You can use them to provide descriptions and background information without getting in the way of instructions. Notes are rendered in the margin in some printed formats.
+
+Tips are optional. You can use them to provide extra useful information or other ways of performing an action like keyboard shortcuts or drag and drop. Tips are rendered in the margin in some printed formats.
+
+Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
+
+**Things to try section**
+
+This section is optional. Suggest one or several activities for people to try out on their own.
+Present a list of ideas for people to try out. Start off very specific with something most people can do based on the materials as presented.
+Continue on with a challenge that involves a small bit of research. It is recommended that research be limited to something that can be found in documentation packaged on OSGeoLive, as users might not be connected to the Internet.
+
+**What next? section**
+
+This section is required. Provide links to any further documentation or tutorials. If your project has no further documentation, include a link to your project's website or wiki or include a contact email or mailing list to join.
+
+== Example file structure
+The quickstart template which includes the basic structure is here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst
+
 
 {{{
@@ -52 +144 @@
 
 
-.. Writing Tip: Overview section
-This section is required and has no heading. Start with a sentence describing what the application is and does. 
-
-This application is a GIS Desktop client for editing and viewing Geospatial data.
-
-.. Writing Tip:
-   Next, describe what will be covered in the Quick Start. Choose a few features to show. If you're showing one or two things, write that in sentence format. If it's three or more, use a bullet list. Optionally, you can also manage expectations about the length of the Quick Start - how much time should the user expect to commit to this activity?
-
-This Quick Start describes how to:
-
-* Add a title and subtitle
-* Add a link `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
-* use the standard map tools
-* apply color to map features using styling
-
-
- .. Writing tip: prerequisites section
-     This section is optional. Mention any prerequisites that are required to complete the Quick Start, for example, internet connection or data to test with.
-
-This guide uses some of the sample data included with OSGeo Live. Make sure you can access /usr/local/share/data.
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. 
+
 
 .. contents:: Contents
-.. Writing Tip:
-  Use headings in your document to automatically generate a table of contents. The headings should start with verbs, and should be the same or similar to what you have said the Quick Start will cover.
+
   
-This is a title
-================================================================================
-
-A title has a line with 80 '=', and you  use them to separate big sections of the quickstart
-
-Here a paragraph is starting because of the blank line above.
-But this line belongs to this second paragraph.
-
-.. Writing Tip:
-  The heading title for the first section is "Start application name". Use numbered steps to describe what to do. Steps start with a verb or action word. Include only one action per step. A description of the expected result is not a new step.
-  Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items. Also refer to this page to describe elements on the UI https://developers.google.com/style/ui-elements
-
-
-
-This is a subtitle
---------------------------------------------------------------------------------
-
-A subtitle has a line with 80 '-', and you  use them to separate sections within the title
-
-The following is an image, and it is being described here
-
-.. image:: /images/projects/<slug>/image_name.png
+Start application name
+======================
+
+From the menu, choose :menuselection:`Geospatial --> Desktop GIS --> uDig`. The application opens.
+
+Porttitor eget dolor morbi non arcu risus quis varius quam. 
+
+   .. image:: /images/projects/<slug>/image_name.png
    :scale: 70 %
 
 
-The image can be described here also
-
-.. this is a comment, because it does not start with a sphinx command
-
-.. TODO I am using a comment to mention some reminder of things to do
-
-
-
-This :menuselection:`Geospatial --> Desktop GIS --> uDig` can be used for a sequence of clicks on menus will look like: `Geospatial ‣ Desktop GIS ‣ uDig`
-
-* This is a bulleted list.
-* It has two items, the second
-  item uses two lines. (note the indentation)
-
-1. This is a numbered list.
-2. It has two items too.
-3. This numbered list
-
-   * Has a bullet list (note the blank line and the indentation)
-   * This bullet has an image (note the blank line and the indentation)
-
-      .. image:: /images/projects/<slug>/image_name.png
-         :scale: 70 %
-.. .. Writing Tip - Images:
- For images, use a scale of 50% from a 1024x768 display (preferred) or 70% from a 800x600 display. Markup the graphic with red circles to highlight any particular areas of note on the GUI (if required). Store images here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/images/projects/1024x768/
-
-.. note::
-  Notes are optional. You can use them to provide descriptions and background information without getting in the way of instructions. Notes are rendered in the margin in some printed formats.
-
-
-.. tip::   Tips are optional. You can use them to provide extra useful information or other ways of performing an action like keyboard shortcuts or drag and drop. Tips are rendered in the margin in some printed formats.
-
-
-The **Bold** and the *Italic*.
-
-The following is for code
-
-::
-
-   Code starts here, (note the blank line between the `::` and the code
-   More code
-
-This is not code
-
-
-The following is `link title <http://this/is/the/external_link.html>`__
-(note back ticks ` and the 2 underscores at the end)
-
-The following is an internal link :doc:`../overview/<other_slug>_overview`.
-
-
-
-
-Things to Try
-================================================================================
-
-This section is optional. Suggest one or several activities for people to try out on their own.
-
-Present a list of ideas for people to try out:
-
-* Start off very specific with something most people can do based on the materials as presented.
-* Continue on with a challenge that involves a small bit of research
-* It is **recommended** that research be limited to something that can be
-found in documentation packaged on OSGeoLive, as users might not be
-connected to the Internet.
+Excepteur sint
+==============
+
+Porttitor eget dolor morbi non arcu risus quis varius quam. 
+
+#. Nisi vitae suscipit tellus mauris a diam maecenas sed. 
+#. Vestibulum lectus mauris ultrices eros in cursus. Pellentesque habitant morbi tristique senectus et. 
+#. Nisi quis eleifend quam adipiscing vitae proin sagittis nisl. Ut venenatis tellus in metus vulputate eu scelerisque felis imperdiet. 
+
+   .. image:: /images/projects/<slug>/image_name.png
+   :scale: 70 %
+
+#. Turpis in eu mi bibendum neque egestas congue quisque egestas. 
+
+
+Sit amet purus gravida
+======================
+
+Et egestas quis ipsum suspendisse ultrices. 
+
+#. Eu sem integer vitae justo. Enim lobortis scelerisque fermentum dui faucibus in ornare. Est ullamcorper eget nulla facilisi etiam dignissim. 
+#. Nulla posuere sollicitudin aliquam ultrices sagittis. Ultrices dui sapien eget mi proin sed libero. Tellus id interdum velit laoreet id donec ultrices. 
+Nunc sed velit dignissim sodales. Elit ut aliquam purus sit amet luctus. 
+#. Proin fermentum leo vel orci porta. Fermentum odio eu feugiat pretium nibh. Nunc mi ipsum faucibus vitae aliquet. Ac ut consequat semper viverra. Velit ut tortor pretium viverra suspendisse. Mauris augue neque gravida in. 
+
+Eleifend quam adipiscing vitae proin sagittis. Risus viverra adipiscing at in tellus integer feugiat scelerisque variu
+
+
+Things to try
+=============
 
 Here are some additional challenges for you to try:
 
-#. Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-   Mauris eget dui vitae estsodales consequat eget vel risus.
-   Fusce suscipit lorem sit amet elementum volutpat.
-#. Try Praesent pretium mauris id porta convallis.
-
-
-What Next?
-================================================================================
-
-This section is required. Provide links to any further documentation or tutorials. If your project has no further documentation, include a link to your project's website or wiki or include a contact email or mailing list to join.
-
-
-* the tutorial
-
-   Maybe have a short description of the tutorial. The tutorial or documentation might not be inside the disk, so use this link style:
-   
-   The link: `link title <http://this/is/the/external_link.html>`__
-
+* Try Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
+* Mauris eget dui vitae estsodales consequat eget vel risus.
+* Try Praesent pretium mauris id porta convallis.
+
+
+What next?
+==========
+
+Here are some other sources of information to keep learning:
+
+* the tutorial - short description of the tutorial. The link: `link title <http://this/is/the/external_link.html>`__
+* Tortor condimentum lacinia quis vel eros donec ac. 
+* Nunc lobortis mattis aliquam faucibus. 
 
 }}}