6

We all know that code reviews are generally a good practice, but what about reviewing documentation? Many devs that I work with will put up wiki pages, javadocs, etc, but most of the time, unless someone else needs it right away the docs will go unnoticed and unreviewed.

Are there any good tools or methodologies for peer reviewing code documentation?

closed as off-topic by gnat, user40980, user53019, Kilian Foth, Dan Pichelman Jan 20 '15 at 15:05

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – Community, Kilian Foth, Dan Pichelman
If this question can be reworded to fit the rules in the help center, please edit the question.

2

Actually, I think your posting contains two different questions, let's start with the simple one first:

are there any good tools or methodologies for peer reviewing code documentation?

I don't think there are "special tools or methodologies", because there is nothing special needed. Peer reviewing documentation works like any other kind of proofreading - you give the documents to the reader, he reads it, adds comments or suggestions for changes and finally you discuss the suggestions. That's all, it works with any kind of documentation technology (of course, some technologies make proofreading and commenting a little bit easier, but that does not change the general methodology).

Many devs that I work with will put up wiki pages, javadocs, etc, but most of the time, unless someone else needs it right away the docs will go unnoticed and unreviewed.

That is actually your second question - in other words "why do lots of people do not take notice of separate code documentation, or don't care for their quality?"

I think this question has been discussed in-depth here on this site, as well as in lots other places. It is a very broad question, but it all boils down to "is additional documentation really worth the effort?" And as long as the answer is not clearly "yes", don't expect to get a different answer to ""is it really worth the effort to review it?"

My personal opinion about this is that any team which is responsible for a certain product has to find the amount of documentation, and the correct abstraction level for the documentation that works for the team and the product. And once you found that, and the team sees a lot of value in that docs, the demand for reviews will arise by itself.

  • I'm really not asking two questions here. I really am trying to figure out how to review wiki documentation. How would that work with this: "you give the documents to the reader, he reads it, adds comments or suggestions for changes and finally you discuss the suggestions." What are you saying, print it out? Send it as a text doc and ask for inline comments? I'm looking for something like crucible... for documentation. Make sense? – javamonkey79 Jan 20 '15 at 3:47
  • @javamonkey79: sorry, but tool recommendations are explicitly off-topic for this site. If you are looking for a tool, name the documentation technology explicit and ask on softwarerecs.stackexchange.com. But don't believe if noone in your team takes notice of code documentation or makes reviews, any kind of tool will change that. – Doc Brown Jan 20 '15 at 7:09
2

Given that any quality produce requires documentation, even if its a getting-started document you should be creating, updating and reviewing the docs.

The problems come when documentation is hard to access, so if you have to check out a word document from sharepoint edit it and then upload it again, you're not going to find many people wanting to make the changes. So I find it best if you assume the documentation is part of the source code, and if you put the document sources alongside the code there's no excuse for not updating it - eg if your documentation is text files in a markup language then doc changes are as easy as editing a big comment. Your CI system can turn those sources into word or PDF or HTML, so you always have up to date documentation that is both easy to edit and easy to review (you just check the scm history diffs).

wiki pages are less easy as they do not closely correspond to SCM history, but you do still have their history you can check, the editor will have to say which pages they changed.

Other than that, there's no tooling for Word documentation reviewing that is any good (you still have to manually go in and read the whole thing to see if it it correct) so you end up having to add a review comment that you updated the docs in section X, chapter Y, page Z. The answer to this is obviously to stop using Word.

Not the answer you're looking for? Browse other questions tagged or ask your own question.