Changes between Version 7 and Version 8 of How to document the quickstart file


Ignore:
Timestamp:
19 Nov 2019, 19:03:19 (4 years ago)
Author:
flicstar
Comment:

Further edits to the page.

Legend:

Unmodified
Added
Removed
Modified

  • How to document the quickstart file

    v7 v8  
    33= How to document the quickstart file
    44
    5 == What is the quickstart?
     5== What is a quickstart?
    66The 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.
    77
    … …  
    2121Write 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.
    2222
     23Write in Restructured Text (RST) format. Docutils provides a good reference for writing in RST format [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]
     24
     25Documentation is built using sphinx. You can use a browser-based sphinx editor to preview your work. For example, https://livesphinx.herokuapp.com/
    2326
    2427=== Notes about markup
    2528
    26 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]
    27 
    28 You can use a browser-based sphinx editor to preview your work. For example, https://livesphinx.herokuapp.com/
    29 
    30 **Section headings**
    31 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.
     29Section 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.
    3230All other section headings characters need only be as long as the heading.
    3331
    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 
    40 1. This is a numbered list.
    41 2. It has two items too.
    42 3. 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
     32Sphinx inline markup:
     33* use :guilabel: for buttons and field names
     34* use :menuselection: for selecting menu items. This typically looks something like, From the menu, choose :menuselection:`View --> Zoom --> Zoom Out`.
     35
     36Use the asterisk symbol for unordered lists, and the hash symbol for numbered steps.
     37
     38Use the following for images:
     39    .. image:: /images/projects/<slug>/image_name.png
    4840         :scale: 70 %
    4941
    50 Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items.
    51 
    52 The following is for a code block
     42Links:
     43* External `link title <http://this/is/the/external_link.html>`__ (note the back ticks ` and the 2 underscores at the end)
     44* Internal :doc:`../overview/<other_slug>_overview`.
     45
     46
     47Code block
    5348
    5449::
    … …  
    5752   More code
    5853
    59 This is not code
    60 
    61 
    62 The following is `link title <http://this/is/the/external_link.html>`__
    63 (note back ticks ` and the 2 underscores at the end)
    64 
    65 The following is an internal link :doc:`../overview/<other_slug>_overview`.
    66 
    67 
    68 === Notation explained
     54
     55=== OSGeoLive notation
    6956
    7057*  Words surrounded by `< >` are to be defined by the person documenting the project
    … …  
    8673
    8774
    88 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
     75It is 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
    8976
    9077
    … …  
    10491
    10592Use headings to create sections and structure in the quickstart. The heading title for the first section is "Start application name".
     93Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
     94
    10695Use 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.
    10796Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style
    … …  
    113102Tips 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.
    114103
    115 Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
    116104
    117105**Things to try section**
    … …  
    126114
    127115== Example file structure
    128 The quickstart template which includes the basic structure is here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst
     116The quickstart template which includes the basic structure is here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst.
     117Take a copy of this file and use it to create your own quickstart.
    129118
    130119
    … …  
    203192
    204193* Try Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    205 * Mauris eget dui vitae estsodales consequat eget vel risus.
    206194* Try Praesent pretium mauris id porta convallis.
    207195
    … …  
    210198==========
    211199
    212 Here are some other sources of information to keep learning:
     200Here are some other resources to learn more about this application:
    213201
    214202* the tutorial - short description of the tutorial. The link: `link title <http://this/is/the/external_link.html>`__