Re: [OSGeoLive] Quickstart 'how to' page and template
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 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
Re: [OSGeoLive] Quickstart 'how to' page and template
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*
[OSGeoLive] Quickstart 'how to' page and template
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
