Which documentation for your code?

Image from https://pixabay.com/it/file-carta-ufficio-1614223/

Suppose you are so good at writing self explanatory code: easy to read and to understand. Congratulations! This is not so common. If you’ve been able to achieve this result, you can afford to say anyone asking you info about your software: read the code!

Well, maybe that’s not right. Although your code is written in an exemplary way, it does not mean that everyone will be able to use it on the fly. Briefly consider who will somehow interact with your code. Apart from end users (you can not absolutely claim that they read your code) there are other technical users of your code. Consider at least the following:

  • Developers who need to use your APIs
    Why should they read your code when they are only interested in public interfaces?
  • System administrators and devops
    Why should they read your code to understand how to configure the application and how to interpret log entries?
  • Developers who have to modify your code
    Okay, maybe these are the only individuals who benefit from your brilliant code writing skills. But why they have to read your code to figure out how to set up a development environment or to guess any code conventions you have used?

It would not be a bad thing to help these people and avoid forcing them to infer information by reading your code, albeit well written. It’s a bit like expecting a driver to disassemble the engine of his own car to see if he needs to refuel petrol or diesel. Or like expecting someone to to see an entire movie to find out the actors who are playing.
In other words, even if your code is readable you still need to write a minimum of documentation to make life easier for other people (or for yourself after some time).

http://geekandpoke.typepad.com/geekandpoke/2010/09/how-to-ensure-quality.html

But what kind of documentation do you need to create in order to support your code?
My suggestion is not to separate the code from the documentation. Do not create elegant documents to put in a specialized repository. One or more text or markdown files should be included within the software project structure. So it’s easier to find and edit them.
As far as content is concerned, I believe that at least the following should be provided:

  • A brief description of the software and its main architecture
  • Instructions on how to setup the development and test environments
  • Instructions on how to make a build and how to run tests
  • Coding convention used
  • Instructions on how to setup in production and how to apply configuration options
  • Instructions on how to interpret log entries and errors
  • API descriptions with usage examples (this should be an automatically generated documentation)

Of course this content should be adapted to the context of your software project. Anyway, your self-explanatory code and your complete documentation will put your professionality in the foreground.