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.

Writing tips

Overview section

This section is required and has no heading. Start with a sentence describing what the application is and does. 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. Mention any prerequisites that are required to complete the Quickstart, for example, internet connection or data to test with.

Contents list

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.

Main body of the quickstart

Use headings to create sections and structure in the quickstart. The heading title for the first section is "Start application name". Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.

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. Refer to the Google Developer Style guide if you need guidance: ​https://developers.google.com/style

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/

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.

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.

Things to try section

This section is optional. Suggest one or several activities for people to try out on their own. Present 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. Continue 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.

What next? section

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.

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.

Sphinx inline markup:

• use :guilabel: for buttons and field names
• use :menuselection: for selecting menu items. This typically looks something like, From the menu, choose :menuselection:View --> Zoom --> Zoom Out.

Use the asterisk symbol for unordered lists, and the hash symbol for numbered steps.

Use the following for images:

.. image

/images/projects/<slug>/image_name.png :scale: 70 %

Links:

• External link title <http://this/is/the/external_link.html> (note the back ticks ` and the 2 underscores at the end)
• Internal :doc:../overview/<other_slug>_overview.

Code block

::

Code starts here, (note the blank line between the :: and the code More code

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 the projects_info.csv file
• The project quickstartfile name is <slug>_quickstart.rst for example udig_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