From kde-usability Thu Aug 26 04:23:19 2004 From: Frans Englich Date: Thu, 26 Aug 2004 04:23:19 +0000 To: kde-usability Subject: Re: KDE Doc: A technical/Organizational view Message-Id: <200408260423.19677.frans.englich () telia ! com> X-MARC-Message: https://marc.info/?l=kde-usability&m=109349454129318 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. > 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 > 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. > 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/ _______________________________________________ kde-usability mailing list kde-usability@kde.org https://mail.kde.org/mailman/listinfo/kde-usability