Changes between Version 10 and Version 11 of How to document the quickstart file
- Timestamp:
- 11/22/19 21:50:58 (5 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
How to document the quickstart file
v10 v11 9 9 == Where to find the quickstarts 10 10 11 The quickstarts are located at:11 The quickstarts are stored at: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart 12 12 13 https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart 13 The quickstarts are published to the OSGeoLive package website: https://live.osgeo.org/en/overview/overview.html 14 14 15 15 16 16 == Writing a quickstart 17 17 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.18 Write in a friendly, conversational style similar to the way a teacher would talk a class through an example. 19 19 20 20 * 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] … … 33 33 **Contents list** 34 34 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.35 Use 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. 36 36 37 37 **Main body of the quickstart** … … 40 40 Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required. 41 41 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.42 Use 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. 43 43 Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style 44 44 … … 61 61 === Notes about markup 62 62 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.63 Section 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. 64 64 All other section headings characters need only be as long as the heading. 65 65 … … 92 92 93 93 * Words surrounded by `< >` are to be defined by the person documenting the project 94 * `<slug>` is the slug name defined on`projects_info.csv` file94 * `<slug>` is the project name which is defined in the `projects_info.csv` file 95 95 * The project quickstartfile name is `<slug>_quickstart.rst` for example `udig_quickstart.rst` 96 96 * Words surrounded by `@ @` are variables
