How to document the quickstart
What is a 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 stored at: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart
The quickstarts are published to the OSGeoLive package website: https://live.osgeo.org/en/overview/overview.html
Writing a quickstart
Write in a friendly, conversational style similar to the way a teacher would talk a class through an example.
- 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
- Documentation is built using sphinx. You can use a browser-based sphinx editor to preview your work. For example, https://livesphinx.herokuapp.com/
Make a copy of the quickstart template and use it as a base to create your own quickstart: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst.
The quickstart is comprised of the following sections:
- Overview
- Contents list
- Main body
- Things to try
- What next?
In the main body, use headings and subheadings to create structure. Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
Notes about markup
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.
All other section headings characters need only be as long as the heading.
Data for sample procedures
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.
OSGeoLive notation
- Words surrounded by
< >are to be defined by the person documenting the project <slug>is the project name which is defined in theprojects_info.csvfile- The project quickstartfile name is
<slug>_quickstart.rstfor exampleudig_quickstart.rst - Words surrounded by
@ @are variables - Words surrounded by
| |are Sphinx variables
| Variable | Example | Action |
|---|---|---|
| @LOGO_<slug>@ | @LOGO_udig@ | Gets the logo image of the project if it exists |
| @OSGEO_KIND_<slug>@ | @OSGEO_KIND_udig@ | Gets the logo of the kind of project within OSGeo as defined into projects_info.csv
|
| @NAME_<slug>@ | @NAME_udig@ | Gets the name of the project as defined into projects_info.csv
|
| @QUICKSTART_<slug>@ | @QUICKSTART_udig@ | Will generate a link to the quickstart if defined into projects_info.csv
|
| @SCREENSHOT_<slug>@ | @SCREENSHOT_udig@ | Places the screenshot to a given standard size |
| |version-<slug>| | |version-udig| | Project's version defined into projects_info.csv
|
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 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
