KDE Doc: A technical/Organizational view

[Frans Englich]

We have many areas which needs documentation. Two crucial issues are where 
those are placed(as in websites), and how far we should split into separate 
documents.

Initially, I would like to ventilate a future project of mine, which I think 
closely relates to this:

The Great Docbook'ing of Developer.kde.org. First of all, it would make 
maintenance easier as docbook does, and it would also take care of much glue 
such as structure/TOC and common constructs such as FAQ. But the largest 
reasons are not those. 
That, in order to build 3rd KDE applications that integrates properly with the 
desktop environment, a developer have to hunt multiple incomplete/informal 
README all scattered over cvs.kde.org and the net, is unacceptable; it hurts 
KDE significantly and especially world domination. That docbook'ed 
dev.kde.org would be a pure technical reference which walks through the KDE 
technologies, for example, combined with chapters about the KDE community. If 
such a document existed, I think there would be a very little need for 
tutorials/HOWTOs and many typical questions on kde-devel etc, would 
significantly drop.

Frans shares evil plans: The KUA[1] project is a website with the docbook 
backend disguised, slowly growing towards a general book about usability. The 
HIG uses docbook too. And with a technical reference, we have better 
websites, and the successive writing of a KDE Developer Book which does not 
become out of sync like the KDE 2 book did. What we will have in 
the end is a cool project, written by hundreds of people, and which can go to 
print with no technical problems, and with no production 
costs(well..). Perhaps 4.1 is reasonable -- then the 4.0 code have settled 
down, and documentation is in a calm state. 

<SNIP>
>  Who     What
>  KDE accessibility   Team accessibility Guidelines (AG)
>  KDE Artists      Community Identify Guidelines (CIG)
>  KDE Usability Team  KDE Human Interface Guidelines (HIG)
>  KDE Documentation  provided docbook expertise
>  KDE developers   input and feedback from the developer's perspective
<SNIP>

> to facilitate this, we will probably be working in Docbook format in a CVS
> module (proposed name: kdeguidelines). Docbook should allow us to create
> html and print (e.g. PDF) versions of the guidelines as well as support the
> high degree of cross-referencing we desire.
<SNIP>

> the AG will take a similar form, and all three guidelines will be linked
> together. it is proposed that they will be housed at a common website
> (http://guidelines.kde.org) and linked to by the appropriate websites
> (artist.kde.org, accessibility.kde.org, usability.kde.org,
> developer.kde.org, etc).

Pessimistic is not fun to sound, but what we're starting here is huge. Three 
docbook(book) projects, a new sub domain, maintenance of existing sub domains 
-- and gluing this all together. It's tons of files, and lots of web work. My 
experience says all projects are initially hyped, and then their 
productivity/work flow drops to 10/25%. This documentation revolution will 
drop in speed, but how much? And can the current plans survive that? In other 
words, that organization has the problem that it's tons of work and it's a 
risky. It's also a big initial threshold for reaching actual result.

The Docbook'ing Of Developer.kde.org will probably happen sooner or 
later, done by someone, because it's a reasonable idea. It would be strategic 
to be prepared and adapted for that future project.


Apart from that multiple guidelines and a new sub domain brings tons of 
maintenance work, it also brings a heavy overhead in using these documents. 
It also means a reduced chance to bring focus on these important issues, and 
it splits developers.

We need focus and developer awareness on usability, but we need it even more 
on a11y. When we separate documents we reduce the chance devs reads the 
second doc -- if a11y is sewn into the usual HIG it will be read on the fly, 
regardless of if a11y involves any itches(yes, it's a crude world). We need 
to keep the amount of documents down, for developers' sake, and in the end  
KDE's. The GNOME folks have sewn a11y into their HIG, and have a separate 
docbook article on about 20 pages(estimation) -- we are most likely talking 
about the same sizes and starting a separate book instead of probably a 
chapter is overkill. Also, I see many a11y adaptions as exceptions from, and 
emphasizations of ordinary Guidelines(but I can of course be wrong), and that 
would then be another reason.

I see the same problem with the artwork front: A lack of usability focus. It 
doesn't focus on usability, but simply on creating (nice looking, cool?) 
artwork. By making the icon guide a section(a part) of the HIG we clearly 
signals it's a /subset/ of usability, and the content becomes related to 
other usability which is also read.

We are in the same boat as Apple and GNOME, and they have their icon guides 
and a11y related in their HIG(not counting technical/implementation papers).

Will this result in a huge HIG? In case we write such huge amounts of 
documentation that we outrun the other two(and if we have a valid reason..) I 
suggest we split it up first then, and it will take a long time before that's 
reached.


Regarding domains;

Apart from the maintenance burden, we again add confusion. If I as developer 
wants to reach the basics of usability and a11y for my app -- what websites do 
I visit? guidelines(GKO), accessibility(AKO), usability(UKO) or 
developer.kde.org(DKO)? Them all? Isn't DKO for developers? The content of 
GKO is solely for developers, and DKO is for developers; we shouldn't have two 
sites for the same thing.
Let's have one central place for developer related materials. Move HIG & KUA 
to DKO and move developer related from AKO to DKO too(application specific is 
untouched). I think that would render UKO useless, which is good -- less 
maintenance. AKO would still have content relevant for the public and hence 
should stay.



How is this practically done?

It will take time before DKO is docbook'ed, and trying to integrate other 
projects(HIG etc.) before that's done would mean duplicate work and a messy 
result. Instead, let's move them to areas/www/developer(not a new module, 
KISS, consistency with other subdomains, and easy access to the resources in 
www) and let a temporary subdomain(or UKO) serve it until DKO is docbook'ed, 
and then moved to areas/www/developer, which then developer.kde.org would 
server. Before DKO is docbook'ed I don't think it would make sense investing 
in framework; we will be busy with content anyway(and the default docbook 
navigation is just fine).

But when DKO is united with the other docbook projects on www/areas/developer, 
we can do a good framework in one place:

* We could use the Cocoon app framework to take care of content generation so 
we don't have to bother with that; PDF and XHTML. I asked sysadmin about 
Cocoon for UKO but got a No, motivated by server load. I think that's wrong, 
Cocoon caches content generation and practically serves static pages; it 
would be less dynamic than the current copy&paste PHP. Cocoon would also be a 
rock for anything else XML related(XInclude, XSL SS processing, or any other 
flexibility and sophistication).

* We could add RSS feeds etc. and make it portal like: It's one central, place 
and investments have a high return.


What are your thought of the technical side of matter?

I recommend not to you the PHP framework with docbook: It's a mess, inflexible 
and ties ones hands; I've tried it twice. It's easily solved by writing an XSL 
for the main web code(needed anyway).


			Frans


1.
http://usability.kde.org/kua/current/