Changes between Version 10 and Version 11 of How to document the quickstart file


Ignore:
Timestamp:
22 Nov 2019 21:50:58 (5 months ago)
Author:
flicstar
Comment:

Incorporated feedback from Cameron on mailing list

Legend:

Unmodified
Added
Removed
Modified
  • How to document the quickstart file

    v10 v11  
    99== Where to find the quickstarts
    1010
    11 The quickstarts are located at:
     11The quickstarts are stored at: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
    1212
    13 https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
     13The quickstarts are published to the OSGeoLive package website: https://live.osgeo.org/en/overview/overview.html
    1414
    1515
    1616== Writing a quickstart
    1717
    18 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.
     18Write in a friendly, conversational style similar to the way a teacher would talk a class through an example.
    1919
    2020* Write in reStructured text (reSt) format. Docutils provides a good reference for writing in reSt format [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html]
     
    3333**Contents list**
    3434
    35 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.
     35Use headings in your document to automatically generate a table of contents. The headings should start with verbs (action words), and should be the same or similar to what you have said the Quickstart will cover.
    3636
    3737**Main body of the quickstart**
     
    4040Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
    4141
    42 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.
     42Use numbered steps to describe what to do. Steps start with a verb (action word). Include only one action per step. A description of the expected result is not a new step.
    4343Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style
    4444
     
    6161=== Notes about markup
    6262
    63 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.
     63Section headings - Use 80 characters above and below the quickstart title. You need 80 because the title uses a slug (the name defined on `projects_info.csv` file - see the OSGeoLive notation section below) and we don't know how many characters the application name is.
    6464All other section headings characters need only be as long as the heading.
    6565
     
    9292
    9393*  Words surrounded by `< >` are to be defined by the person documenting the project
    94   * `<slug>` is the slug name defined on `projects_info.csv` file
     94* `<slug>` is the project name which is defined in the `projects_info.csv` file
    9595* The project quickstartfile name is `<slug>_quickstart.rst` for example `udig_quickstart.rst`
    9696* Words surrounded by `@ @` are variables