Collaborative Coding and Documentation

Question

At a new research job, I will be part of a long-term effort to clean up a pretty extensive Java codebase (7+ years of development). It currently resides on SVN, but I am considering Mercurial.

There are perhaps two types of people collaborating on the project. Type 1: people who will be developing a lot of code and writing documentation. Type 2: people who are users of the code and have very good suggestions about documentation and usability.

I imagine a workflow like so:

1. A developer reviews a section of code and (re)writes documentation (in-code Javadoc/Doxygen style)
2. Developer commits code
3. Versioning server updates HTML documentation
4. Type 2 users can review the documentation and make comments on the documentation page itself (wiki style?). Collaborators can have a discussion here.
5. Developers look at the comments and go to step 1.

I am looking for any suggestions about the proposed workflow and ideas about tools which will help accomplish it. Thanks!

Answer 1

I strongly suggest a commits mail list: by making the changes easily visible to everyone, as they happened, our code review was significantly better: errors were caught earlier, suggestions were made while the code was still fresh in the developer's mind, and everyone felt more aware of what everyone else in the team was working on.

Answer 2

I suggest that you make the type 2 (customers?) people part of the team directly so they can help the developers right away, instead of having to write documents.

That should make this much quicker since it increases communication and shortens the feedback loop immensely.