Best Practices: Documentation Tools


Whilst the phrase “undocumented code is unusable” is sometimes rather extreme, it is almost guaranteed that anyone attempting to use, develop or maintain a piece of undocumented code will have face an uphill battle. As a result, undocumented software represents a large overhead in terms of time and effort. Therefore, code documentation needs to address two sometimes wildly disparate audiences: end users, and current and future developers. Thankfully, it is seldom necessary for a single piece of documentation to serve both masters, however this does mean that requirement for documentation can feel like a significant burden for the developer. Fortunately, there are a number of tools and techniques that exist to aide us in efficiently creating good documentation. In Documentation Tools: Overview and Best Practices, we discuss why it is necessary to write documentation, the attributes that form good user and developer documentation, and examine some of the tools available for streamlining this process.


Documentation Tools

Section 5.2 of Documentation Tools: Overview and Best Practices contains a table providing an overview of commonly used documentation tools, which is replicated and updated below. If we are missing one of your favourite documentation tools, please contact us.

Editor Languages Pros Cons
DOXYGEN C, C++, C#, objective C, Python, VHDL, Fortran, IDL, Java, PHP, D
  • Outputs to HTML, RTF (MSWord), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages
  • Can generate various diagrams and graphs illustrating interrelations within the source
  • Can generate browsable version of code cross-referenced with documentation
  • Can do the above for undocumented sources.
  • Widely used and well supported
  • Formatting is very specific, so converting into or out of Doxygen-compatable formatting can be time consuming
  • Docs tend to be visually cluttered
  • Little capacity for non-technical documentation, i.e. notes, examples, rationale, etc.
FORD Fortran
GHOSTDOC C#, VB, Javascript
  • Strong emphasis on visual editing – edit documentation directly with changes propagated back into source code
  • UI tools for XML formatting
  • Requires Visual Studio
  • Free version is limited with more expensive options available for more features ($60-100 per user)
  • Already part of the Java 2 SDK
  • Lacks diagrammatic functionality
  • Need to manually enter HTML tags
PDOC Python 2, 3
  • Quick and simple setup
  • Python-specific
  • Particularly good inheritance tracing
  • Clean, readable output
  • Can pass resulting object model to Sphinx for nicer output type
  • Python 2 – specific
SPHINX C, C++, Ada, Python, Ruby, Fortran, JavaScript, PHP
  • Clean, modern formatting of output documentation
  • Outputs to HTML, LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
  • Supports reStructuredText in docstrings
  • Lacks the useful ability to extract API documentation from C++ headers.
  • Setup requires multiple configuration steps even with the provided quickstart script
SWAGGER >40: android, aspnet5, aspnetcore, async-scala, bash, cwiki, csharp, cpprest, dart, …
  • Incredibly broad language support
  • Open-source
  • Ensures OpenAPI Specification compliance
  • Automatically generate server and client code and SDKs
  • Interactive UI allowing documentation editing and live API calls allows for interactive tutorials/examples
  • Tight focus on API development
  • No hypermedia support
  • Limited customization

This list is by no means exhaustive and we also recommend looking at wikipedia’s overview.