[APBeta] Documentation using a wiki

[Paul Rodman]

On Jun 20, 2010, at 3:29 PM, Dan Kuchta wrote:

> Personally, I'm not a big fan of online documentation, wiki or otherwise.  If manuals are well written and well organized, they can add dramatically to the usability of the software.  By the same token, poorly written manuals can be miserable to wade through.  While I'm sure writing manuals is not your favorite task, you are actually quite good at it and in my opinion, your manual is better than most commercial software I've purchased.  In fact, it was one of the reasons I purchased AstroPlanner to begin with.
> 
> On the other hand, I can certainly understand that you have limited time and would rather spend it writing code instead of manuals.  A wiki can be an effective way of getting the information out there and letting the community help with the updates and additions.  What you tend to lose is that coherent, organized "train of thought" that runs through a well written manual like yours.

I hear you. I still hope to have a manual. The V1.x manual has probably saved me a lot of support over the years (anecdotal evidence). Yes, it's a pain to write, but not the most onerous task I face (I'd rather be manual writing than trying to fix unreproducible Windows bugs, for example). It's also easier to slap together a manual using a word processor than messing around with wiki formatting, uploading images, etc. 

If I was doing it myself.

The reason I like the wiki approach is (a) I can get editorial feedback, and editors can fix my grammar or logical errors/omissions on the spot, (b) third-parties (i.e. you guys) can add your own stuff to the manual and make it better, and (c) it's easier to modify dynamically as features change.

Thinking about this further, for the sake of timeliness, I might be forced to go with a traditional manual. I am offloading the "reference" stuff into the built-in help system, but that's even slower than a wiki.

Paul R.