19 Feb
2012
19 Feb
'12
3:55 a.m.
On Saturday 18 February 2012 08:24:14 pm Darrell Anderson wrote:
I think the easiest way to do this is to have those with commit access keep a running list
(possibly on the Etherpad) of what they are changing that would entail a documentation
update. Obviously, a bugfix that doesn't change or add any features would not require
updated documentation -- most such bugfixes are simply to help with crashes, security, and
general stability. Instead, the list would only changes that occur at the user-visible
level (i.e. feature changes and additions).
One problem to consider with the documentation team is that not everybody will use every
program. For example, not everybody will use KDevelop (TDevelop?) because not everybody
will be developing TDE apps. I'd suggest we have people assigned to programs they
actually use. Of course, we'd have to account for when someone doesn't use every
possible feature of an app they do use, e.g. if someone chooses to use Konqueror instead
of Amarok to sync their music to their PMP (most PMPs show up as a flash drive).
--
Kris Gamrat
Ark Linux webmaster
http://www.arklinux.org/
We would
probably need a few people to make sure that
documentation is up-to-date with what is currently in 3.5.13
(for example, was the documentation updated when the TMenu
search box was added?), and then to make sure it is still
up-to-date with new changes/features from R14 on.
I believe no documentation has been updated with any of the changes made after 3.5.10.
:(
I have been thinking about this process for many weeks. I believe this topic ties into
our recent discussions about having a review board. The bugzilla seems to be a possible
avenue to trigger reviews, but often code patches are committed to the source code without
a formal bug report. How do we monitor those commits for documentation reviews?
Perhaps somebody (preferably two or more people) as part of a documentation review team.
Perhaps this team reviews the GIT patch logs on a daily or weekly basis and then populates
a punch list somewhere to note which documentation files need updating.
If we do something like that then we need to be serious about documentation. That is,
documentation that is not updated becomes a release blocker. I've been in the tech
writing business many years and if documentation is not elevated to Blocker status then
you can guess what happens. :)
Currently we have no process to ensure documentation is reviewed and updated. We need a
way to encourage documentation reviews.
How do folks with other software projects handle this?