creating a LAStools user guide

[Martin Isenburg]

Hello,

this user forum is a fairly good reference for how to use LAStools
(especially if you search with the right keywords). However, there is
an emerging need for a proper user guide. Does anyone have suggestions
how to realize that in a way that is both organized and directed, but
can also exploit the collective knowledge of LAStools users. I was
thinking of a Wiki-style platform that could also be used for bug
reporting and creating tutorials or training exercises. Each change
would go through a review process until that person is proven worthy
of being knighted into LASlibhood by the rapid LiDAR lasso ... (-;

Realizing this will require some kind of hosting package. I was
thinking of using a managed Wordpress hosting that is able to
integrate this envisioned Wiki-style tutorial. After being scorned by
a developer (whose opinion I regard highly) for using GoDaddy (*) when
registering the lastools.org domain - that particular company is off
the table. (-; In general I would prefer a European hosting
service ...

If you have suggestions or if you are interested in helping me to set
this up, please email me directly at mar...@rapidlasso.com and I share
the main suggestions and the final verdict as a follow-up response in
one condensed message.

Regards,

Martin @rapidlasso

(*) quote "Godaddy, Martin? Of all folks I would expect you to boycott
the nastiness that is the right wing, no-warrant spy supporting, break
DNS because we're USA and can do whatever the hell we want without due
process Godaddy registrar :)

I was a godaddy user until they supported SOPA and SIPA and anti-gay
marriage and all those wonderful USA'ian right wing causes and it
pissed me off. I moved all my stuff to gandi.net in wonderful
socialist France away from the no due process takedown of any USA-
based DNS registrar. They've been nice to work with and easy to use."

[Howard Butler]

On Nov 16, 2012, at 10:39 AM, Martin Isenburg <martin....@gmail.com> wrote:

> Hello,
>
> this user forum is a fairly good reference for how to use LAStools
> (especially if you search with the right keywords). However, there is
> an emerging need for a proper user guide. Does anyone have suggestions
> how to realize that in a way that is both organized and directed, but
> can also exploit the collective knowledge of LAStools users. I was
> thinking of a Wiki-style platform that could also be used for bug
> reporting and creating tutorials or training exercises. Each change
> would go through a review process until that person is proven worthy
> of being knighted into LASlibhood by the rapid LiDAR lasso ... (-;

As someone who's managed documentation for major projects such as MapServer.org, gdal.org, and libas.org, I have been through CMS-based documentation efforts, wiki-based doc efforts, SGML/Docbook efforts, etc. The best is reStructuredText + Sphinx [1] with version control and a plain old static website host. MapServer.org's docs are nearly 1000+ pages as a PDF. Sphinx allows us to maintain it in essentially plain text and output it to formats that users want to consume such as HTML, PDF, eBook, Windows Compiled Help, etc. Over the years, MapServer has iterated through four different documentation systems, and this current one based on this architecture has lasted the longest and been the most successful by any metric you wish to use.

A wiki is like a garden in that it needs gardeners. One gardener has to do a lot of work to maintain even a small plot, and if they let it go for a week or two, they spend 2x the time pulling weeds. Documentation is more like a cooked meal, not plants growing raw vegetables. People want to eat it, not pull weeds, fertilize, pick the food, prep the food, and cook it. A wiki can be a good support tool for documentation development collaboration, but it makes for a poor canonical documentation repository.

CMS is like a garden too, except with a bunch of overhead and red-tape rules about who can do what when. People end up fighting the CMS to get information in, and once it's in there, it gets really hard to get it back out again.

Lightly marked up text, like reStructuredText or Markdown plus a static website and revision control gives you the most flexibility and the simplest documentation system to manage. People can issue pull requests to a github repository for changes/updates, and you can merge them in at your leisure and pin the version of documents to releases. A side wiki to support collaboration or documentation workflow is helpful as an intermediary, but the final product needs to be the canonical, semi-permanent documentation set that can be tied to a release version. A wiki or CMS-based approach makes it very hard to tie documentation sets to specific versions. It is not always sufficient to say "use the latest", because people can get really frustrated when you do say that and they can't migrate for whatever reason (like they've built your tools into a larger more complex system, or they can't afford to upgrade at this moment, etc).

Hope this helps,

Howard

[1] http://sphinx-doc.org/

[Kevin Gallant]

Hi  Martin,

  A wiki-style platform would be useful.  I have been looking at http://www.wikidot.com/learnmore:project

Wikidots is a better developer site.

Regards,

Kevin Gallant

--
Download LAStools at
http://lastools.org/
Visit the LAStools group at
http://groups.google.com/group/lastools/
Be social with LAStools at
http://www.facebook.com/LAStools
http://www.twitter.com/LAStools