[OSGeoLive] Quickstart 'how to' page and template

Cameron Shorter cameron.shorter at gmail.com
Fri Nov 22 15:42:52 PST 2019 

Hi Felicity,

A number of comments inserted into the doc below. My comments are in 
italics and proceeded by /Cameron: .../


  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.

/Cameron: Nice intro./


    Where to find the quickstarts

The quickstarts are located at:

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

/Cameron: The quickstarts are *stored* at .../

/Cameron: We should also list where the quickstarts are published to./


    Writing a quickstart

Write in a friendly, conversational style similar to the way a teacher 
would talk a class through an example. TheQuickStarts?for R 
andGeoServer?do this very well.

/Cameron: It looks like hyperlinks for Quickstarts and GeoServer are 
broken, and I assume you'd prefer to be linking to R./

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

/Cameron: Note, when looking at templates at this URL, comments are not 
visible unless you view source (which is not obvious). As this is a 
template, I'd be inclined to move instructions out of the invisible 
commented ".. Writing Tips" into visible "Writing Tips:..." with obvious 
formatting show it is a comment.
/

/Cameron: I see that the example is using specific udig references. I 
suggest we move this to a generic example. While we could consider a 
defining a new imaginary project, I think we can relatively easily 
adjust the udig example to be a "generic desktop GIS" application. Keep 
almost the same as before, and just remove udig specific references. 
While creating generic screen shots would be ideal, I suggest stick with 
the existing udig screenshots for the moment.
/


      Writing tips

/Cameron: I see that you have duplicated the same writing tips in both 
the wiki and in the template. I'm strongly against duplication of text. 
Reasons:/

/Cameron: 1. It becomes a maintenance nightmare. Maintainers need to 
update docs in two places, creating more work.
/

/Cameron: 2. Incidental fixes will regularly only be applied to one 
version of the docs, resulting in the docs becoming inconsistent and 
often contradictory. (It appears there are already a few inconsistencies.)
/

/Cameron:3. By writing the same information in two places, we are 
setting up the reader to read the same information twice. While there 
are some advantages to having the information presented differently, I 
think overall it is a net loss in value./

/Cameron: So, I propose we only store writing tips within the template, 
and don't duplicate in the wiki as well.
/

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

/Cameron: Nice description, especially when followed by an example./

Optionally, you can also manage expectations about the length of the 
Quick Start - how much time should the user expect to commit to this 
activity?

/Cameron: The above is in the template but not the wiki. I'd suggest we 
shouldn't add an optional statement for this. Either be specific about 
how much time is expected, or not. I'd err on specifying time, but 
suggest for the moment that we follow what most people have done to 
date. I've seen both options argued. Specify time: Helps people know how 
long the piece is. Don't specify time: People might feel silly if they 
take too long./

Mention any prerequisites that are required to complete the Quickstart, 
for example, internet connection or data to test with.

/Cameron: I suggest there should be a heading "Prerequisites", which is 
optionally included./

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

/Cameron: I suggest we don't assume people understand what a "verb" is. 
Use: "Headings should start with verbs *(action words)*, ..."/

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

/Cameron: Suggest "Steps start with a verb *(an 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/

/Cameron: I wrote this original suggestion for screenshot sizes and 
after seeing plenty feel I made the wrong suggestion. I find that 
reducing the size by 50% will often make text too small to read. A size 
reduction of 70% is better. For the moment, lets keep our current 
recommendation in order to stay in line with most quickstarts, but keep 
this in mind for future (eg for TheGoodDocsProject)./

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.

/Cameron: The following sections are not in the template document. We 
should either move the content from the wiki to the template, or 
reference the wiki from the template. I'm mildly in favour of 
referencing the wiki from the template. We probably should reference the 
wiki from the top of the template, as well as the bottom./


      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.

/Cameron: I realise the term "slug" is defined below, but it probably 
should be expanded here./

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

/Cameron: Terminology could be tweaked slightly here to be clearer.  
(Vicky should be able to help here).
/

/Cameron: //Define <slug>. I'm assuming it is the projectname, as used 
for filenames, which is defined in projects_info.csv.
/

/Cameron: What is the difference between "variables" and "sphinx variables"/

/Cameron: Define @OSGEO_KIND@ I assume it is a grouping of similar 
project types, like Desktop GIS.
/

  * Words surrounded by|< >|are to be defined by the person documenting
    the project
      o |<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

Last modified 
<https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20quickstart%20file?action=diff&version=10>2 
days ago 
<https://trac.osgeo.org/osgeolive/timeline?from=2019-11-19T19%3A51%3A32-08%3A00&precision=second>


      Download in other formats:

On 21/11/19 4:14 pm, Felicity Brand wrote:
> Hello,
>
> I have done some work updating the 'How to document the quickstart
> file' page on the wiki and the template for the quickstart.
>
> They should go hand-in-hand (I have linked from each to each other.)
> I'm not sure where users might start, so I was trying to cover
> different angles of entry.
>
> I would appreciate a review of the page and the template - preferably
> by the end of next week which is the conclusion of the Season of Docs
> period.
>
> https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20quickstart%20file
>
> Thanks
> Felicity
> _______________________________________________
> osgeolive mailing list
> osgeolive at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/osgeolive

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/osgeolive/attachments/20191123/0a18b11a/attachment-0001.html>

More information about the osgeolive mailing list