|Version 11 (modified by 3 years ago) ( diff ),|
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.
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.
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 %
link title <http://this/is/the/external_link.html>(note the back ticks ` and the 2 underscores at the end)
- Internal :doc:
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.
- Words surrounded by
< >are to be defined by the person documenting the project
<slug>is the project name which is defined in the
- The project quickstartfile name is
- Words surrounded by
@ @are variables
- Words surrounded by
| |are Sphinx variables
|@LOGO_<slug>@|| ||Gets the logo image of the project if it exists|
|@OSGEO_KIND_<slug>@|| || Gets the logo of the kind of project within OSGeo as defined into |
|@NAME_<slug>@|| || Gets the name of the project as defined into |
|@QUICKSTART_<slug>@|| || Will generate a link to the quickstart if defined into |
|@SCREENSHOT_<slug>@|| ||Places the screenshot to a given standard size|
||version-<slug>||| || Project's version defined into |
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