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


Ignore:
Timestamp:
18 Nov 2019 20:04:21 (10 months ago)
Author:
flicstar
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • How to document the quickstart file

    v5 v6  
    33= How to document the quickstart file
    44
    5 == Where to find the quickstart files
    6 
    7 The quickstart files are located at:
     5== What is the quickstart?
     6The 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.
     7
     8
     9== Where to find the quickstarts
     10
     11The quickstarts are located at:
    812
    913https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
    1014
    11 == Notation
    12 
    13 For this documentation:
     15
     16== Data for sample procedures
     17In 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.
     18
     19== How to write a quickstart
     20
     21Write 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.
     22
     23
     24=== Notes about markup
     25
     26Source 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]
     27
     28Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items.
     29
     30**Section headings**
     31Use 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.
     32All other section headings characters need only be as long as the heading.
     33
     34**Basics**
     35
     36* This is a bulleted list.
     37* It has two items, the second
     38  item uses two lines. (note the indentation)
     39
     401. This is a numbered list.
     412. It has two items too.
     423. This numbered list
     43
     44   * Has a bullet list (note the blank line and the indentation)
     45   * This bullet has an image (note the blank line and the indentation)
     46
     47      .. image:: /images/projects/<slug>/image_name.png
     48         :scale: 70 %
     49
     50
     51The following is for a code block
     52
     53::
     54
     55   Code starts here, (note the blank line between the `::` and the code
     56   More code
     57
     58This is not code
     59
     60
     61The following is `link title <http://this/is/the/external_link.html>`__
     62(note back ticks ` and the 2 underscores at the end)
     63
     64The following is an internal link :doc:`../overview/<other_slug>_overview`.
     65
     66
     67=== Notation explained
    1468
    1569*  Words surrounded by `< >` are to be defined by the person documenting the project
     
    3084Most 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 ]
    3185
    32 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
    33 
    34 
    35 
    36 = `quickstart_<slug>.rst` File Structure
     86
     87It 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
     88
     89
     90=== Writing tips
     91
     92**Overview section**
     93
     94This section is required and has no heading. Start with a sentence describing what the application is and does.
     95Next, 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.
     96Mention any prerequisites that are required to complete the Quickstart, for example, internet connection or data to test with.
     97
     98**Contents list**
     99
     100Use 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.
     101
     102**Main body of the quickstart**
     103
     104Use headings to create sections and structure in the quickstart. The heading title for the first section is "Start application name".
     105Use 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.
     106Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style
     107
     108For 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/
     109
     110Notes 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.
     111
     112Tips 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.
     113
     114Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
     115
     116**Things to try section**
     117
     118This section is optional. Suggest one or several activities for people to try out on their own.
     119Present 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.
     120Continue 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.
     121
     122**What next? section**
     123
     124This 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.
     125
     126== Example file structure
     127The quickstart template which includes the basic structure is here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst
     128
    37129
    38130{{{
     
    52144
    53145
    54 .. Writing Tip: Overview section
    55 This section is required and has no heading. Start with a sentence describing what the application is and does.
    56 
    57 This application is a GIS Desktop client for editing and viewing Geospatial data.
    58 
    59 .. Writing Tip:
    60    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?
    61 
    62 This Quick Start describes how to:
    63 
    64 * Add a title and subtitle
    65 * Add a link `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
    66 * use the standard map tools
    67 * apply color to map features using styling
    68 
    69 
    70  .. Writing tip: prerequisites section
    71      This section is optional. Mention any prerequisites that are required to complete the Quick Start, for example, internet connection or data to test with.
    72 
    73 This guide uses some of the sample data included with OSGeo Live. Make sure you can access /usr/local/share/data.
     146Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
     147Ut 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.
     148
    74149
    75150.. contents:: Contents
    76 .. Writing Tip:
    77   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.
     151
    78152 
    79 This is a title
    80 ================================================================================
    81 
    82 A title has a line with 80 '=', and you  use them to separate big sections of the quickstart
    83 
    84 Here a paragraph is starting because of the blank line above.
    85 But this line belongs to this second paragraph.
    86 
    87 .. Writing Tip:
    88   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.
    89   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
    90 
    91 
    92 
    93 This is a subtitle
    94 --------------------------------------------------------------------------------
    95 
    96 A subtitle has a line with 80 '-', and you  use them to separate sections within the title
    97 
    98 The following is an image, and it is being described here
    99 
    100 .. image:: /images/projects/<slug>/image_name.png
     153Start application name
     154======================
     155
     156From the menu, choose :menuselection:`Geospatial --> Desktop GIS --> uDig`. The application opens.
     157
     158Porttitor eget dolor morbi non arcu risus quis varius quam.
     159
     160   .. image:: /images/projects/<slug>/image_name.png
    101161   :scale: 70 %
    102162
    103163
    104 The image can be described here also
    105 
    106 .. this is a comment, because it does not start with a sphinx command
    107 
    108 .. TODO I am using a comment to mention some reminder of things to do
    109 
    110 
    111 
    112 This :menuselection:`Geospatial --> Desktop GIS --> uDig` can be used for a sequence of clicks on menus will look like: `Geospatial ‣ Desktop GIS ‣ uDig`
    113 
    114 * This is a bulleted list.
    115 * It has two items, the second
    116   item uses two lines. (note the indentation)
    117 
    118 1. This is a numbered list.
    119 2. It has two items too.
    120 3. This numbered list
    121 
    122    * Has a bullet list (note the blank line and the indentation)
    123    * This bullet has an image (note the blank line and the indentation)
    124 
    125       .. image:: /images/projects/<slug>/image_name.png
    126          :scale: 70 %
    127 .. .. Writing Tip - Images:
    128  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/
    129 
    130 .. note::
    131   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.
    132 
    133 
    134 .. 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.
    135 
    136 
    137 The **Bold** and the *Italic*.
    138 
    139 The following is for code
    140 
    141 ::
    142 
    143    Code starts here, (note the blank line between the `::` and the code
    144    More code
    145 
    146 This is not code
    147 
    148 
    149 The following is `link title <http://this/is/the/external_link.html>`__
    150 (note back ticks ` and the 2 underscores at the end)
    151 
    152 The following is an internal link :doc:`../overview/<other_slug>_overview`.
    153 
    154 
    155 
    156 
    157 Things to Try
    158 ================================================================================
    159 
    160 This section is optional. Suggest one or several activities for people to try out on their own.
    161 
    162 Present a list of ideas for people to try out:
    163 
    164 * Start off very specific with something most people can do based on the materials as presented.
    165 * Continue on with a challenge that involves a small bit of research
    166 * It is **recommended** that research be limited to something that can be
    167 found in documentation packaged on OSGeoLive, as users might not be
    168 connected to the Internet.
     164Excepteur sint
     165==============
     166
     167Porttitor eget dolor morbi non arcu risus quis varius quam.
     168
     169#. Nisi vitae suscipit tellus mauris a diam maecenas sed.
     170#. Vestibulum lectus mauris ultrices eros in cursus. Pellentesque habitant morbi tristique senectus et.
     171#. Nisi quis eleifend quam adipiscing vitae proin sagittis nisl. Ut venenatis tellus in metus vulputate eu scelerisque felis imperdiet.
     172
     173   .. image:: /images/projects/<slug>/image_name.png
     174   :scale: 70 %
     175
     176#. Turpis in eu mi bibendum neque egestas congue quisque egestas.
     177
     178
     179Sit amet purus gravida
     180======================
     181
     182Et egestas quis ipsum suspendisse ultrices.
     183
     184#. Eu sem integer vitae justo. Enim lobortis scelerisque fermentum dui faucibus in ornare. Est ullamcorper eget nulla facilisi etiam dignissim.
     185#. Nulla posuere sollicitudin aliquam ultrices sagittis. Ultrices dui sapien eget mi proin sed libero. Tellus id interdum velit laoreet id donec ultrices.
     186Nunc sed velit dignissim sodales. Elit ut aliquam purus sit amet luctus.
     187#. 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.
     188
     189Eleifend quam adipiscing vitae proin sagittis. Risus viverra adipiscing at in tellus integer feugiat scelerisque variu
     190
     191
     192Things to try
     193=============
    169194
    170195Here are some additional challenges for you to try:
    171196
    172 #. Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    173    Mauris eget dui vitae estsodales consequat eget vel risus.
    174    Fusce suscipit lorem sit amet elementum volutpat.
    175 #. Try Praesent pretium mauris id porta convallis.
    176 
    177 
    178 What Next?
    179 ================================================================================
    180 
    181 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.
    182 
    183 
    184 * the tutorial
    185 
    186    Maybe have a short description of the tutorial. The tutorial or documentation might not be inside the disk, so use this link style:
    187    
    188    The link: `link title <http://this/is/the/external_link.html>`__
    189 
     197* Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
     198* Mauris eget dui vitae estsodales consequat eget vel risus.
     199* Try Praesent pretium mauris id porta convallis.
     200
     201
     202What next?
     203==========
     204
     205Here are some other sources of information to keep learning:
     206
     207* the tutorial - short description of the tutorial. The link: `link title <http://this/is/the/external_link.html>`__
     208* Tortor condimentum lacinia quis vel eros donec ac.
     209* Nunc lobortis mattis aliquam faucibus.
    190210
    191211}}}