The future of docbook documentation

[Alexander Dymo]

Hi!
I was updating our doxygen docs today and also looked at docbook documentation
we have in svn.

Today there're 3 books:
- KDE Architecture Overview (kdearch)
  book by Bernd Gehrmann written in 2002
- The KDevelop Programming Handbook (kde_app_devel)
  book by Ralf Nolden and Caleb Tennis (1999-2002)
  this book is actually more like KDE programming handbook
- KDevelop User Manual
  2002-2005 by various authors

Those books mostly contain outdated information. I agree it still might be
sometimes relevant and sometimes useful, but that doesn't make them
less outdated.

I'd like us to decide what to do with them. I think kdearch and kde_app_devel
have to be simply removed because techbase.kde.org now contain
an up-to-date information about KDE architecture and KDE application
development. We don't have to maintain those books anymore.

So the remaining problem is our user manual. KDevelop3 development
clearly shows that we were able to consistently maintain
1) our website which is near to perfect thanks to Amilcar
2) our Platform API docs which are quite good and are of kdelibs quality 
    at least.

But we failed to maintain the user manual. The contributions to the manual
were rare and sporadical despite the 3.x stable series has been in development
for 3 years.

I can think of 3 options to improve the situation with user manual:
1. Make conscious effort to update and maintain the docbook 
version of the manual.
pros:
 - there's a good translation infrastructure in place for docbook manuals
cons:
 - developers with svn access has no interest in maintaining manual
 - users have high barriers to contribute (svn access, docbook xml syntax,
  long patch-apply cycles through the mailinglist)

2. Use a wiki instead of docbook to maintain documentation so that more 
people  could contribute.
pros:
- easy to maintain by all interested parties (techbase for example was a huge
  success, wikibooks are also usually in a good shape)
cons:
- harder to translate
- very hard to generate printable versions

3. Follow Ruby/Rails model - write a very very good book and sell it for a
relatively cheap price (15-20$) in electronic (pdf) and printed form.
pros:
- book writers become actually interested in maintaining the book and
  working on book updates and new releases because they will have some
  money from that work
- with good knowledgeable writers the book will be very useful
  (I know that from my Ruby/Rails coding experience when it's often faster
  and easier to look for the solution in the book than in API docs or wikis)
cons:
- no freely available user manual
  (is that a problem? currently we have the free, but totally useless manual)
- it is unclear how to do translations in this case

Comments? Opinions?