On Saturday 18 February 2012 08:24:14 pm Darrell Anderson wrote:
> > 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?
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/
Attachments: