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.shor...@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@lists.osgeo.orghttps://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
