GNOME Bugzilla – Bug 339173
gnome-utils docs component is not useful
Last modified: 2012-07-16 14:31:19 UTC
gnome-utils is made up of many tools. each has its own separate manual.
having a single component 'docs' in the gnome-utils bugzilla product causes problems:
* bugs are reported about documentation that do not specify the application, eg Bug 172476
* the documentation team cannot effectively use bugzilla to manage documentation bugs in this area
I am not sure what the solution should be, ccing shaun.
Can you expand on the second problem, "the documentation team cannot effectively use bugzilla to manage documentation bugs in this area"?
Seems like that is the same as the previous one.
Also see bug 338663 for general docs problems.
Ex: A doc team member who wants to work on the Log Viewer manual can't obtain a list of just those bugs.
I'll add a comment on 338663, as this is probably a problem with all products that group several apps together.
Noticed default assignee for gnome-utils is firstname.lastname@example.org.. if you want some general alias instead, just ask.
Solving this is not easy.
Some options I can think of:
- searchable field with the app name. this would be specific to some problems (I would hate that)
- Remove all docs components and use docs keyword. hate that as well as our reports usually are based upon product&component.
- Change simple-bug-guide to ask for application name.. wouldn't make it searchable, but perhaps by reassigning manually + using describeuser.cgi?
- Create special product called docs-for-nasty-products and move bugs from here to that product (and also change simple-bug-guide)
Plus I still want a better browse.cgi, but I'll do that in the other bug.
Fifth option: Multiple-program modules (gnome-utils, gnome-applets, gnome-games, etc.) pretty much all have a component for each program. So give them a component for each document as well. So for gnome-utils, we'd replace the docs component with gfloppy-docs, gdict-docs, gsearchtool-docs, and logview-docs. (After that, convince the maintainers that human-readable component names would be much nicer.)
The potential problem here is that we'll get an explosion of components, and maintainers of these modules will have to look at a *much* larger list of components in their product summary pages. As a developer, I sympathize.
We haven't done multiple docs components much before for a number of reasons:
1) The reason I just listed.
2) Documentation writing wasn't done so much in the community.
3) The documents in the multiple-program modules are usually small.
But yeah, bugs like #172476 pretty much suck. And if bugzilla ever gets some RPC love, then I'll add to Yelp a clicky-clicky form to submit documentation bugs. And then poor Joachim will be overwhelmed with bugzilla.
Now, here's an idea you can take to the bugzilla hackers: Have a way to tag each component as a particular type. The types should be flexible, of course. Then every documentation component could be tagged as "documentation". Then hackers could specify in their preferences that they don't want to see documentation-type components in their product summaries, and writers could easily get a list of all documentation-type components.
There's probably a ton of other great uses for typed components.
with my hat as maintainer of gnome-utils firmly on: I really don't care that much about having a -docs component for every (active) tool; after all, gnome-utils ships with five tools. so, if you want me to go ahead, I can create a -docs component for gfloppy, gsearchtool, gdict and logview.
(In reply to comment #4)
> (After that, convince the maintainers that human-readable component names
> would be much nicer.)
I had to keep gdict+gdict-applet for gnome-dictionary to avoid migrating bugs from the old dictionary to the new - but all the other components maps the name of the application on the CVS.
This is OBSOLETE by bug 660377 (split of the product), however none of the six new products has a -docs component.
Shaun, would the docs team prefer to have this for all new products?
(NEEDINFO for the time being)
Shaun, do you have any update for the bug ?
Closing this bug report as no further information has been provided. Please feel free to reopen this bug if you can provide the information asked for.