The future of docbook documentation

[Matt Rogers]

On Saturday 17 March 2007 15:15, Alexander Dymo wrote:
> 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.
>

I agree. They should be removed.

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

4. Make KDevelop easy enough to use that a manual is not required for most 
things. This would mean that if we weren't able to maintain a manual that it 
wouldn't be that big of a loss, and if we were able to maintain a manual, 
even better. 
--
Matt
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20070317/c308c0d3/attachment.sig>