Documentation

If your product is complex, or if you want a way to showcase your features, you might consider producing user documentation. This comes in many different forms:

  • Getting started guide (web page, PDF): the basics to use your software
  • Tutorials (web pages): walk through simple tasks with examples
  • User Guide: comprehensive documentation

Documentation can be printed and bundled (uncommon), distributed with your software (PDF, other formats, more common) or hosted on your website (very common).

Keep in mind that this all takes effort. Tailor your documentation to the complexity of your product (and the likelihood of users actually taking the time to read it!)

Release notes

Every public release should include release notes: a list of changes that you have made to your product for that particular release. Depending on the nature of your product, and your relationship with your users, the details can be fairly general (“added support for Windows 11”) or incredibly detailed (“fixed bug XXX”).

The release notes are also a good place to put things like

  • OS or hardware compatibility details
  • copyright and license information
  • information on how users can contact you or get help

Release notes are typically released in one of the following ways:

  • a readme.txt file included in your distribution.
  • a popup window in your application that includes these details.
  • a page on your website (if you do this, put a way to open that page from within your application).

Suggestions

A discussion of how to write effective documentation is beyond the scope of this course, but we make some broad suggestions:

  • Consider Markdown as an authoring format. You can then convert markdown to PDF, EPUB, or HTML for publishing using pandoc. This site, for example, is authored in Markdown and then converted to a website using Hugo.
  • If you wish to create developer documentation (including class diagrams and so on), there are specialized authoring tools. Dokka can generate Javadoc, HTML or Markdown documentation from Kotlin code (much as Javadoc does for Java code).
  • Finally, IntelliJ IDEA can generate class diagrams from source code. Right-click on the project file, then select Diagrams from the popup menu.

Generated class diagram Generated class diagram