[[PageOutline(1-2)]] = 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 * `` is the project name which is defined in the `projects_info.csv` file * The project quickstartfile name is `_quickstart.rst` for example `udig_quickstart.rst` * Words surrounded by `@ @` are variables * Words surrounded by `| |` are Sphinx variables ||= Variable =||= Example =||= Action =|| || @LOGO_@ || `@LOGO_udig@` || Gets the logo image of the project if it exists || || @OSGEO_KIND_@ || `@OSGEO_KIND_udig@` || Gets the logo of the kind of project within OSGeo as defined into `projects_info.csv`|| || @NAME_@ || `@NAME_udig@` || Gets the name of the project as defined into `projects_info.csv` || || @QUICKSTART_@ || `@QUICKSTART_udig@` || Will generate a link to the quickstart if defined into `projects_info.csv` || || @SCREENSHOT_@ || `@SCREENSHOT_udig@` || Places the screenshot to a given standard size || || |version-| || `|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