Changes between Version 11 and Version 12 of How to document the quickstart file


Ignore:
Timestamp:
11/22/19 22:21:31 (5 years ago)
Author:
flicstar
Comment:

Removed writing tips because they are now in the template

Legend:

Unmodified
Added
Removed
Modified

  • How to document the quickstart file

    v11 v12  
    2323Make 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.
    2424
    25 === Writing tips
     25The quickstart is comprised of the following sections:
    2626
    27 **Overview section**
     27* Overview
     28* Contents list
     29* Main body
     30* Things to try
     31* What next?
    2832
    29 This section is required and has no heading. Start with a sentence describing what the application is and does.
    30 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.
    31 Mention any prerequisites that are required to complete the Quickstart, for example, internet connection or data to test with.
    32 
    33 **Contents list**
    34 
    35 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.
    36 
    37 **Main body of the quickstart**
    38 
    39 Use headings to create sections and structure in the quickstart. The heading title for the first section is "Start application name".
    40 Include about three to five sections, each with a heading and numbered steps, screenshots and code blocks as required.
    41 
    42 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.
    43 Refer to the Google Developer Style guide if you need guidance: https://developers.google.com/style
    44 
    45 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/
    46 
    47 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.
    48 
    49 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.
     33In 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.
    5034
    5135
    52 **Things to try section**
    53 
    54 This section is optional. Suggest one or several activities for people to try out on their own.
    55 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.
    56 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.
    57 
    58 **What next? section**
    59 
    60 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.
    6136=== Notes about markup
    6237
    6338Section 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.
    6439All other section headings characters need only be as long as the heading.
    65 
    66 Sphinx inline markup:
    67 * use :guilabel: for buttons and field names
    68 * use :menuselection: for selecting menu items. This typically looks something like, From the menu, choose :menuselection:`View --> Zoom --> Zoom Out`.
    69 
    70 Use the asterisk symbol for unordered lists, and the hash symbol for numbered steps.
    71 
    72 Use the following for images:
    73     .. image:: /images/projects/<slug>/image_name.png
    74          :scale: 70 %
    75 
    76 Links:
    77 * External `link title <http://this/is/the/external_link.html>`__ (note the back ticks ` and the 2 underscores at the end)
    78 * Internal :doc:`../overview/<other_slug>_overview`.
    79 
    80 
    81 Code block
    82 
    83 ::
    84 
    85    Code starts here, (note the blank line between the `::` and the code
    86    More code
    8740
    8841=== Data for sample procedures