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

[Hamish]

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)


>    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.


> 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)


> 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.


> 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. :-)


best,
Hamish