В Чтв, 30/03/2006 в 11:02 -0600, Shaun McCance пишет: > On Thu, 2006-03-30 at 16:34 +0100, Andrew Sobala wrote: > > Sergej Kotliar wrote: > > >> On Fri, 2006-03-24 at 21:15 +0100, Vincent Untz wrote: > > >> > > >>> Le vendredi 24 mars 2006 à 16:20 +0300, Nickolay V. Shmyrev a écrit : > > >>> > > >>>> While looking on discussion of removed screensaver button and work > > >>>> work on GNOME docs translation, one interesting idea came to my mind. > > >>>> > > >>>> Usually UI changes are accepted without change in user documentation > > >>>> thus making docs obsolete (for example, user docs still mention > > >>>> screensaver button and even more, they tell user about "Add to panel" > > >>>> popup menu with submenus). From other side, maintainers often reject > > >>>> patches with bad formatting or other code guidelines violation. Isn't > > >>>> it > > >>>> better to require that every UI-related patch should have doc patch as > > >>>> well. Usually new API should be documented, why do we ignore user docs? > > >>>> They aren't less important than coding style, probably they even more > > >>>> important. > > >>>> > > >>> The thing is that the docs are usually not maintained by the modules > > >>> maintainers. It's easy to reject (well, mark as "needs-work") patches > > >>> because of formatting or non-documentation of new API since those are > > >>> stuff that is the job of the maintainer. Not to mention that I wouldn't > > >>> qualify as someone who can write some part of the doc :-) > > >>> > > >>> Also, this is why the UI freeze does exist. Maybe it's too late for > > >>> documentation people, though. IMHO, a good first step would be to ask > > >>> maintainers to list all the big changes that has been done before UI > > >>> freeze. > > >>> > > >> Agree completely. Another option, however, is that whenever > > >> maintainers do something, they file a bug against the docs > > >> component of their product in bugzilla. Generally speaking, > > >> this means that every time a developer spends hours and hours > > >> implementing a new feature, he needs to spend an additional > > >> five minutes writing a very basic outline of what the feature > > >> does in bugzilla. A particularly nice maintainer might also > > >> list anticipated common gotchas or other quirks. > > >> > > > > > > > > >> Heck, if the feature (or substantial UI change or whatever) > > >> was implemented in response to a bug, the maintainer needn't > > >> even file a new docs bug. He can just change the component > > >> of the existing bug, rather than closing it. > > >> > > >> This would give the documentation team a much better chance > > >> of documenting as we go, rather than in one lump sum at the > > >> end of the release cycle. > > >> > > >> -- > > >> Shaun > > >> > > > > > > An even easier solution would be to add the keyword UICHANGE to > > > bugzilla, and let maintainers mark bugs with it whenever they > > > commit anything that changes the UI. In many cases, I think the > > > info in the bugreport would be enough. Of course - if it doesn't > > > have a bug report, one would have to be filed as Shaun suggested. > > > > > One issue with that is that the bug would also be marked FIXED. Docs > > people would have to check for UICHANGE in open *plus* resolved bugs in > > the timeframe since the last release, which can get messy given that > > people branch at different times. > > Right. Maintainers won't want to leave those bugs laying > around open, because they get in their way. I don't know > how everybody else works, but I generally use bugzilla as > my TODO list. If my bug list were full of things that I'd > already done, it would make bugzilla less useful. > > On top of that, it's hard enough for documentation folks > to use bugzilla for documentation things already. Bugs > are spread out across so many products with varying names > of components for documentation. (A few still don't even > have docs components, despite my constant pestering.) We > often just want to say "What can I do?" rather than "What > needs to be fixed in this document?" That's already not > easy, and if we had to look for keywords outside our docs > components as well, it would just make things harder. > > -- > Shaun >
Let me disagree with Vincent's point that maintainer isn't able to update user docs. Usually they contains just a set of phrases like: To print document choose Menu->Print That's all, we write API docs, why can't programmer write two lines like above? Moreover there is quite advanced documentation guide. The main question here to my opinion is a bit different - how to make this practice more mandatory. _______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
