Changes between Version 4 and Version 5 of How to document the quickstart file

Timestamp:

3 Nov 2019, 14:15:30 (4 years ago)

Author:

flicstar

Comment:

Updated with writing tips as part of work done during Google Season of Docs 2019

How to document the quickstart file

@@ -52 +52 @@
 
 
-First sentence defines what the application does.
-You may also need to include a sentence of two describing the domain.
-Eg: For a Business Intelligence application, you should describe what
-Business Intelligence is.
+.. Writing Tip: Overview section
+This section is required and has no heading. Start with a sentence describing what the application is and does. 
+
+This application is a GIS Desktop client for editing and viewing Geospatial data.
+
+.. Writing Tip:
+   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. 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?
 
 This Quick Start describes how to:
 
 * Add a title and subtitle
-* Add a link
-* `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
+* Add a link `Web Map Service (WMS) <http://www.opengeospatial.org/standards/wms>`__
 * use the standard map tools
 * apply color to map features using styling
 
+
+ .. Writing tip: prerequisites section
+     This section is optional. Mention any prerequisites that are required to complete the Quick Start, for example, internet connection or data to test with.
+
+This guide uses some of the sample data included with OSGeo Live. Make sure you can access /usr/local/share/data.
+
 .. contents:: Contents
+.. Writing Tip:
+  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 Quick Start will cover.
   
 This is a title
@@ -74 +84 @@
 Here a paragraph is starting because of the blank line above.
 But this line belongs to this second paragraph.
+
+.. Writing Tip:
+  The heading title for the first section is "Start application name". Use numbered steps to describe what to do. Steps start with a verb or action word. Include only one action per step. A description of the expected result is not a new step.
+  Use Sphinx inline markup such as :guilabel: for buttons and field names; and :menuselection: for selecting menu items. Also refer to this page to describe elements on the UI https://developers.google.com/style/ui-elements
+
+
 
 This is a subtitle
@@ -109 +125 @@
       .. image:: /images/projects/<slug>/image_name.png
          :scale: 70 %
+.. .. Writing Tip - Images:
+ 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/
+
+.. note::
+  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.
 
 
-.. note::
-  Notes are used to provide descriptions and background information without
-  getting in the way of instructions. Notes will likely be rendered in
-  the margin in some printed formats.
-
-
-.. tip::   Tips are used to provide extra useful information, and will 
-  likely be rendered in the margin in some printed formats.
+.. tip::   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.
 
 
@@ -144 +158 @@
 ================================================================================
 
-This section is highly recommended, and should provide pointers further things to try.
+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:
@@ -165 +179 @@
 ================================================================================
 
-
-This section is highly recommended, please provide links to further tutorials and other documentation.
+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.