[Live-demo] Getting OSGeo-Live Quickstart writing guidelines right

[Cameron Shorter]

On 27/05/11 16:09, Hamish wrote:
> Cameron wrote:
>>    * We should add a Table of Contents, as per:
> fwiw, IMHO for docs with 3 or less sections TOCs aren't needed.
>   (ie same rule as wikimedia's auto-TOC uses)

I can be swayed either way on providing a TOC.
Most quickstarts have ~ 15 steps, with a heading for each step. See all 
headings here:
http://adhoc.osgeo.osuosl.org/livedvd/docs/en/quickstart/quickstart.html#application-quick-starts

Hamish, I think you are suggesting that we shouldn't provide a list of 
steps as a TOC as 4 pages of Quickstart is not really long enough?

>
>>     Version:
>> We should include the OSGeo-Live version and Application
>> version.
> already in the .rst header, which seems enough to me, but
> no objection other than that the greater the maintenance
> burden the less that gets done, and the harder it is to keep
> people involved. optimize for automation whenever possible.

I'd like to see if I can publish the version from the .rst tag. As we 
are publishing to the web, and as docs are being translated, it will not 
be obvious to the reader which version of OSGeo-Live a quickstart is 
written for, or which version of the software it was written for.
>
>> Reference Material:
>> Some projects link to tutorial or reference material which
>> has been copied onto OSGeo-Live. I suggest we remove this,
>> and instead point at material on the external web.
>> If we do keep it, we should reference via a http://localhost
>> URL rather than via a /usr/local/... filename. (That way it
>> can be referenced from http://live.osgeo.org/... as well)
> mmmph, I'd prefer to leave on-disc stuff functional, and as
> Jody suggests do a quick search&  replace for path names for
> the website docs. (simple to do with 'sed -i'; I'm already
> doing that for the makefile target in the nightly doc build job)

I'm ok to defer to Jody and Hamish on this and leave documentation on 
OSGeo-Live.
What I suggest is that all documentation be made visible via a 
http://localhost/data/.../file url. We can do this by providing 
hyperlinks in /var/www directory (or similar).

Then in our quickstarts, we can provide relative links to our on disk 
documentation.

During publishing to http://live.osgeo.org, we will need to work out a 
process to copy the extra documentation across as well.

>
>> OpenStreetMap:
> (those were written&  are currently maintained by me)
>
>> * There are a number of applications written up under
>> OpenStreetMapTools. I'm included to suggest that they should
>> be broken up with their own pages,? There are five of them
> As long as I'm looking after them I'd keep them grouped together.
> If anyone else wants to take over maintainership of OSM they'd
> be most welcome to do that, and could manage it any way they like.
> JOSM and Merkaartor could certainly use an expanded quickstart
> with screenshots&  tutorials, especially JOSM as it's a bit
> weird until you get the hang of it. Potlatch is not shipped on
> the disc (it's fully online), but it may be worth having a
> quickstart for that as well as a community service.
>    [these are the 3 main OSM editors]
>
> Gosmore and osm2pgsql are fringe enough wrt the focus of the disc
> that I'm not really inclined to expand their quickstarts much,
> but same as with the rest of the OSM stuff, I'd welcome a patch.

Yes Hamish, you already have a huge commitment to OSGeo-Live and I 
appreciate the extra effort that would be required for one person to 
break these docs apart.
If you are fine with it, I'll look around for a volunteer to break these 
docs apart.


>
>> plus Prune which is written separately.
> Prune is a completely separate app.
>
>
>> Data:
> see my earlier email.
>
>
>> Example OSGeo-Live Web Services:
>> I wonder how hard it would be to set up a demo server with
>> OSGeo-Live web services installed, such that external users
>> to try it out. (This is not required for our documentation,
>> but it would be a nice addition)
> the adhoc VM maybe/might/could be used for that, but I expect
> the security and maintenance burden would be rather ugly&  the
> SAC team would want to delegate that responsibility to the users.
> Actually as it would be a complicated weave probably it would
> want its own VM so others using adhoc would not be adversely
> affected by its wild west nature. shrug.
> A really nice idea though, /if/ you can find a willing sys-
> admin team and can convince everyone to ring-fence their apps
> &  not do custom apache hacks etc. (takes much firm discipline)
> I'd love to see it happen; I'd hate to be left as the one who
> had to support it. :-)

Yes, we can put on the "wish-list" till an enthusiastic volunteer steps 
forward.

>
> best,
> Hamish
>


-- 
Cameron Shorter
Geospatial Director
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

Think Globally, Fix Locally
Geospatial Solutions enhanced with Open Standards and Open Source
http://www.lisasoft.com