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
formathttp://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@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
_______________________________________________
osgeolive mailing list
osgeolive@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/osgeolive
