Re: [Audacity-quality] Where to track issues with inbuilt docs?
A free multi-track audio editor and recorder
Brought to you by:
aosiniao
From: James C. <cr...@in...> - 2010-09-07 09:54:38
|
On 06/09/2010 22:29, ga...@au... wrote: > Any views on having a "docs" product on Bugzilla to store issues with > built-in docs (e.g. to include doxygen and major holes in code comments?) > If so, should we still store issues with the Manual solely on the Manual > Wiki much as now, so that all editors can comment on the major issues > summarised on the ToDo page? The manual is a wiki with talk pages. Issues with the manual should be tracked on the talk pages and with todos. Sometimes there will be a need for a higher level 'discussion', e.g. a recent feedback request leads to "shouldn't we have a troubleshooting section in the manual?" (no, but we might consider a page pointing users to the main wiki tips etc). Those higher level discussions can happen on mailing lists. The source code has comments including some doxygen comments. Issues with the comments and doxygen coverage should be tracked in the source code. We already do this, e.g. *//Answer-me: why do we take the reciprocal here?* which will later lead to an explanatory comment. Sometimes there will be a need for a higher level 'discussion', e.g. "shouldn't we doxygenate every single function?" (no, that's too granular for us, but we may want to rename some functions so they say better what they do). We maybe can get some more conventions for communication-in-the-source-code, e.g consistently using TODO: or just using initials, *//GA: Is mDuration snapped or not?* Then ask, 'please review the GA: comments'. The linux man pages, the text on ohloh and similar could perhaps best be handled by pages on the wiki like this one. http://wiki.audacityteam.org/wiki/Linux_man_Page -1 on a docs product in bugzilla on basis that with these mechanisms already in place I don't think there is enough volume of issues that can't be tracked this way. +1 on a summary issue in Audacity product about documentation. This is mainly so that we can give it a P number. I think it valid, for example, that if the manual said nothing about label linking that could be a P2. The summary bug would mainly point to rather than replicate our documentation tracking. --James. |