[FM Discuss] Does FLOSS Manuals hurt other doc efforts?

[Lachlan Musicman]

Ok, I hope I'm not repeating others - I wanted to write on this when
it first came through, but I've been dead busy, and don't really have
time to read all the mails in this thread.

On the question of does it take over documentation efforts, I think
it's a matter of the software in question, and documentation use
cases.

The Command Line book is the best around for what it is. My comparison
is Django. Those guys do documentation _excellently_. Seriously, it's
fucking amazing - as they write the code, it's commented in source,
and that's turned into the docs by sphinx (I think). They have a 4
part tutorial for beginners that couldn't be bettered by FM, and the
rest is essentially low level documentation. When I say low level, I
mean "every command/syntax/system available in django" is documented
in a way that a nerd that was using django could work it out
(essentially  API docs). Nerd is the operative word there - it's not
software for newbies, unless they are specifically wanting to learn
Django.

Having said that, Django isn't regular software. It's certainly not
Thunderbird (conceivably used by many desktop users),
Wordpress/Drupal/Joomla (_can_ be used by beginner sysadmins
relatively easily, as well as seasoned types (ok, those that don't
spit *bah, php* at you (with reason))), and it doesn't have as many
broad, easy and fascinating use cases as the command line.

Another example is: we now have an excellent Thunderbird manual for
the end user use case. I certainly don't see TB writing their
dev/admin guides in FM. If I was starting some new software, I'd
definitely be thinking about using FM for the user facing
documentation first - it solves a lot of problems like ease of use,
find-ability, multi format export, wiki based/version controlled, etc.
For admin/dev level documentation, I don't think it really fits, but
that is not FM's use case (to my mind).

I agree with the statements "the more docs the better" especially for
new users of software, and I agree with the idea of multi homed
ecosystems - the OLPC/Sugar FM is great on that level, just like "How
To Think Like A Computer Scientist" or "Learn Python the Hard Way" -
introductory texts or gateways to deeper levels of subjects.

It is for these reasons I think we need not worry, although I would be
skeptical if booki became _the_ documentation platform. As I mentioned
above, open healthy ecosystems are useful. Bloody Hell, could you
imagine if Aco and Adam ran the bloody world's documentation effort?
;P

I hope all that made sense.
cheers
L.