How to document the quickstart file

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 located at:

​https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart

Data for sample procedures

In order 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.

How to write a quickstart

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.

Write in Restructured Text (RST) format. Docutils provides a good reference for writing in RST 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/

Notes about markup

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. 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

OSGeoLive notation

• Words surrounded by < > are to be defined by the person documenting the project
  • <slug> is the slug name defined on 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

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, 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 or 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.

Example file structure

The quickstart template which includes the basic structure is here: ​https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/quickstart/_template_quickstart.rst. Take a copy of this file and use it to create your own quickstart.

:Author: <author's name>
:Reviewer: <reviewer name>
:Version: <OSGeoLive version from which this documentation is valid>
:License: Creative Commons Attribution-ShareAlike 3.0 Unported  (CC BY-SA 3.0)



@LOGO_<slug>@
@OSGEO_KIND_<slug>@

********************************************************************************
@NAME_<slug>@ Quickstart
********************************************************************************


Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. 


.. contents:: Contents
   :local:

  
Start application name
======================

From the menu, choose :menuselection:`Geospatial --> Desktop GIS --> uDig`. The application opens.

Porttitor eget dolor morbi non arcu risus quis varius quam. 

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


Excepteur sint
==============

Porttitor eget dolor morbi non arcu risus quis varius quam. 

#. Nisi vitae suscipit tellus mauris a diam maecenas sed. 
#. Vestibulum lectus mauris ultrices eros in cursus. Pellentesque habitant morbi tristique senectus et. 
#. Nisi quis eleifend quam adipiscing vitae proin sagittis nisl. Ut venenatis tellus in metus vulputate eu scelerisque felis imperdiet. 

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

#. Turpis in eu mi bibendum neque egestas congue quisque egestas. 


Sit amet purus gravida
======================

Et egestas quis ipsum suspendisse ultrices. 

#. Eu sem integer vitae justo. Enim lobortis scelerisque fermentum dui faucibus in ornare. Est ullamcorper eget nulla facilisi etiam dignissim. 
#. Nulla posuere sollicitudin aliquam ultrices sagittis. Ultrices dui sapien eget mi proin sed libero. Tellus id interdum velit laoreet id donec ultrices. 
Nunc sed velit dignissim sodales. Elit ut aliquam purus sit amet luctus. 
  * Tortor dignissim 
  * convallis aenean
  * turpis egestas integer 
#. Proin fermentum leo vel orci porta. Fermentum odio eu feugiat pretium nibh. Nunc mi ipsum faucibus vitae aliquet. Ac ut consequat semper viverra. Velit ut tortor pretium viverra suspendisse. Mauris augue neque gravida in. 

Eleifend quam adipiscing vitae proin sagittis. Risus viverra adipiscing at in tellus integer feugiat scelerisque variu

.. tip:: Eget est lorem ipsum dolor sit amet. Nibh nisl condimentum id venenatis.


Things to try
=============

Here are some additional challenges for you to try:

* Try Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
* Try Praesent pretium mauris id porta convallis.


What next?
==========

Here are some other resources to learn more about this application:

* the tutorial - short description of the tutorial. The link: `link title <http://this/is/the/external_link.html>`__
* Tortor condimentum lacinia quis vel eros donec ac. 
* Nunc lobortis mattis aliquam faucibus.