В Сбт, 09/09/2006 в 04:55 +0200, BJörn Lindqvist пишет: > On 9/8/06, Don Scorgie <DonScorgie blueyonder co uk> wrote: > > Doc people do not have enough time. Its as simple as that. As shaunm > > pointed out, this release we got 4 weeks to update the documentation. > > This included 3 new modules needing docs, as well as lots of updates to > > lots of other docs. The doc team has been on skeleton staff ever since > > I've known it. Most of the docs are now pretty out of date. Add in a > > desire to have translated docs and basically, the doc team has negative > > time to do the required work. The great part about it is that for the > > other 5 months, the doc team is pretty much sitting around, twiddling > > thumbs and thinking up plans for world domination [1]. The writers > > can't really do their thing with a moving target. > > 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? > Exactly, and although it's a not reasonable to wait for translations update as Adam pointed, C locale documentation should be updated by change author. As for translations we don't have much problem with them now, when we support more than 40 languages. Moreover, I think we need more polices and guidelines like HIG. There should be API guideline (I don't quite understand all those statements that we now know how good API look, today callbacks are used instead of signals often and it's certainly not a good way of writing API). We need a testing guideline (and a test violation should be considered as a regression and reverted without discussion). As mentioned above, maintainers should provide their roadmap while branching. It was good tradition in previous cycles, but now I've seen a lot of project branched without providing any future plans. It would be nice to get updates of already submitted plans, how many points are finished and how many points are shifted to the next release cycle. For example, what's the state of this list: http://live.gnome.org/GnomeArchitecture/Progress We must document design decisions when they are made. Documentation should include arguments and decisions made. GEP http://developer.gnome.org/gep/gep-0.html was the greates thing here and I wonder why it's not used now It may restrict our freedom, but only this way can do big changes and assure quality.
Attachment:
signature.asc
Description: =?koi8-r?Q?=FC=D4=C1?= =?koi8-r?Q?_=DE=C1=D3=D4=D8?= =?koi8-r?Q?_=D3=CF=CF=C2=DD=C5=CE=C9=D1?= =?koi8-r?Q?_=D0=CF=C4=D0=C9=D3=C1=CE=C1?= =?koi8-r?Q?_=C3=C9=C6=D2=CF=D7=CF=CA?= =?koi8-r?Q?_=D0=CF=C4=D0=C9=D3=D8=C0?=