[OSGeoLive] Quickstart 'how to' page and template

Fri Nov 22 21:38:34 PST 2019

Thanks heaps for your comments Cameron. I will incorporate your suggestions.

I had already removed the uDig-specific content from the template but you
won't have seen it because it's in a PR.
https://github.com/OSGeo/OSGeoLive-doc/pull/538

I totally agree with you about duplication and was in two-minds about where
some of that content should live. I will make it so that the writing tips
are in the template and the higher-level guidance is on the 'How to' wiki
page.

Cheers
Felicity

On Sat, Nov 23, 2019 at 10:42 AM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> 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. The QuickStarts? for R and
> GeoServer? 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>
>    <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
>       - <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 listosgeolive at lists.osgeo.orghttps://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/620e53b3/attachment-0001.html>