[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Software quality and documetation, was: Core KDE member about HIG^W female contributors

Patricia Jung wrote:
<aj@azure.humbug.org.au>  wrote:
But writing and bug-finding /are/ subordinate though -- in the sense they only happen after the code's written...
When it comes to documentation: not quite.

Well, depends whether we're talking what actually happens, or what could happen... :)

Documentation can be a means of quality insurance, and this power is far too seldom used, not only in Open Source development. The people who write the best code I know write documentation alongside or even before coding: The code has to follow documentation, otherwise it's a bug :), at least documentation and code are never allowed to get out of sync. Which means documentation _is_ development, not just something subordinate.

Well, that makes coding subordinate to documentation (if it really does "follow" the documentation), which is no fun. Why, it might even comply with some ISO standards or similar and we can't have *that*... :)

In a scenario like this documentation and usability are not just nice-to-have but an inherent part of development and equally important as writing code, and it finally leads you to better software, to software that is aware of its users and tasks and not just aware of how things are easiest, smartest to implement. But it requires a paradigm shift: Coders are no longer allowed to see documentation as a nasty add on, as something subordinate and documentation people don't simply have to follow the software they get but allowed and required to intervene.

So, I don't care for all the "no longer allowed" or "required to intervene" stuff; but having people helping design programs so it's easy to document and understand seems like an interesting idea -- but I wonder how, or even if, that'd actually work... Do you even get dedicated documenters sticking around a project unless you're something pretty large like Gnome? And if so, how do you get a documenter/whatever that actually sticks with a bit of software?


Reply to: