Question

I want to document a Java project I’m working on. In the past I’ve typically documented the design and software API in a wiki. However, after recently using Mockito for mocking tests, I was impressed at the amount and quality of project-level documentation in the actual javadocs.

My question is, do people typically use Javadocs for documenting the higher level view of the project (e.g. architecture, design decisions etc), or is this kind of information best documented in (say) a wiki?

Answer 1

It depends on who your audience is.

If your audience is going to be primarily using the API, it is generally better to invest in clear concise descriptions (with examples) in your Javadoc. If the audience is likely to never see the API, then it is better to maintain your documentation outside of Javadoc. This is primary a function of how the documentation is navigated; Javadoc navigation facilitates the programming process.

As for whether you wish to put the documentation in a wiki or in a PDF, again it depends on the audience. If the only reason for wiki is to have a web facing HTML representation of the documentation, using something similar to Docbook might provide such documentation with the added benefit of ability to generate PDF representations of the same documentation. If you really have an active community, wiki shines in the ability of allowing near-strangers to modify your documentation.

Determine if the strengths of the products align with your needs, and if they do, then it’s the right choice.