On Thu, 2006-09-14 at 11:22 +0200, BJörn Lindqvist wrote: > > > Then lets stop the target! If I understand you correctly, the > > > development process from the documentors point of view is kind of > like > > > this. > > > > > > * Five months were developers play and pretty much destroy all the > docs we make. > > > * Four weeks were we can undo the damage caused and make GNOME > understandable. > > > > > > Maybe this problem can be solved by elevating the documentations > and > > > the translations status in the project? For example, patches are > very > > > seldom accepted if they introduce regressions in the software. But > > > regressions in the docs aren't counted in the same way. New code > very > > > often changes applications behaviour so that the manual becomes > > > invalid. What if the documentation and translation regressions > were > > > counted in the same way as code regressions? > > > > > > To me, that makes sense. An untranslated string is just as > annoying as > > > a frequently segfaulting program. So lets treat the problems the > same. > > > Code that changes behaviour shouldn't be committed unless the > > > documentation is updated. User visible strings shouldn't be > changed > > > unless the translations are updated. Something like that? > > > > 1. Code truly is more important than documentation, that's why > it's > > treated more importantly; > > I disagree slightly. Bad docs means lowered usability. For example, > try this: open gnome-terminal, Edit->Current profile->compatibility > tab. Now I consider myself fairly computer-savvy but I can't figure > out what those settings do. Pressing the help button and reading the > documentation is unhelpful. So the settings on that tab pane are > completely wasted for me and, I suspect, for 99.9% of all > gnome-terminal users since they are incomprehensible. > > But IF the docs had been written at the same time as the tab pane was > programmed, I believe that the problems with that pane would have > became apparent. Many features are easy to implement but hard to > document.
I wrote about a similar scenario about a year ago, except I wrote about the Evolution account editor dialog. See the section "The Case for Help" here: http://www.gnome.org/~shaunm/quack/mallard.xml In this situation, the documentation does actually exist. It's just not very good documentation. If we required people to submit documentation with all patches, I fear we'd end up with more documentation like that. Technically complete, but practically useless. -- Shaun _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
