Questions about documentation

Question

Are questions about writing/improving documentation appropriate and on-topic for Code Review? And if so, should there be a documentation tag?

Let's be clear--I'm not talking about questions seeking help interpreting official documentation from Apple, Java, Microsoft, etc. These questions, if anything, would be more appropriate on Stack Overflow.

I'm also not talking about self-documentation via class/method/variable names and comments (although questions looking for help with these things could also use a "documentation" tag).

Instead, I'm talking about... suppose I've written a small open-source project and posted it on GitHub. I feel confident about my code and I'm not interested in the code being reviewed. Instead, I'd like help writing and improving the official documentation that I'm providing to go with the project so that future users can most easily understand what all the methods and properties and variables etc are all there for and what they all mean and how the project should be used.

Answer 1

A source file has two audiences:

1. The compiler, for which we have to write working code. This is of no interest on Code Review, as all code is supposed to be already working.
2. A human reader, for which we format our code, think about good naming, and explain our code via comments. Documentation falls into this category.

For example, a review of this source snippet:

/** Frobnicate the object
  *
  * Returns a frobnicated copy
  */
public SomeClass frobnicate() {
    ....
}

Could be reviewed like

You could use the @return directive for the return value. Also, The documentation is just stating the same thing as the type signature, and is therefore of little use. You could explain what frobnication means in the context of your project. You should also mention that an InvalidFrobnicationException will be thrown if this.frobnicator is null.

However, such reference documentation is just a small subset of possible documentation – tutorials and guides would certainly not be on topic here, as the quality of writing and not the source code of the implementation is the main concern.

For questions about writing documentation, Writers or Programmers might be a better fit, depending on the focus of the question. Reviews here on Code Review can (and should) also touch upon documentation, but the docs shouldn't be the main focus: docs are an important part of the source, but they are not code.

Answer 2

I don't see how we could help in reviewing the documentation of code without seeing the code itself.

Therefore, the question is on-topic as long as the code to be documented, and it's documentation is provided within the question.

For many languages (such as Java and C# at least) it's convention to use a specific documentation-style right next to your methods and classes. Therefore, I often see the documentation as part of the code.

Answer 3

My instinct is to say that documentation is not code, and thus is not reviewable.... We have had a number of discussions about pseudocode, and they have all resulted in 'we do not review pseudocode', and 'we do not review pseudocode' (on-topic item #3).

Documentation is close to pseudocode.... right?

In general, certain languages have documentation styles, so, in the sense that the documentation is really directives to a documentation-engine (Javadoc, pod, DoxyGen)... still, it is not a language, and it is not a program.

My vote is 'NO, we do not review documentation'.

Answer 4

One type of 'documentation' is sample code, which shows an example of how to use an API: that (sample code) would be more-or-less on-topic, assuming it works.