Living Documentation: The Examples Directory

Not too long ago, I blogged about having what I call ‘living documentation’.  This is documentation that stays updated based on the current code.  Today I want to discuss a practical way to do this with a Python example, although it can be applied to other languages.

Documentation

The Typical Python Package Structure

In Python, the typical package will have the following structure:

  • package_name (contains source code – this is named the same as the package itself)
  • tests (contains unit test code)
  • setup.py (the script used to install the package)

Other files may be in the Python package, but these are some basic directories and files.  If you look at the Flask project on Github, it also has an examples directory at the same level as the tests and package_name directory.  That directory has several different examples using Flask.

Once a Python package is installed, the source code gets put into a certain location on your hard disk so Python knows how to access it when you import something.

The Examples Directory

Example

Here where I work, we recently create an examples directory with code that showed how to use the package.  I was writing code that used this package, so I looked at that examples directory to determine how to use it.

Within about a minute, I knew exactly how to use that code.  This example served as a form of documentation that immediately showed me how I could use it.  It was a huge eye-opener for me, because it saved me a lot of time.

Now imagine that example code is run through continuous integration every time a commit is made to source control.  I can then guarantee if my unit tests are good enough, my example will always be updated with the current version of code.  If not, my CI server will send me a notification that I broke the examples.

So in the future, I get that quick example to help me write code using that package… and it’s always going to work!  I can quickly learn to use a package by seeing examples of its use.  It will not go out of date thanks to continuous integration.

Conclusion

One could theoretically build on this concept to even get higher levels of documentation, such as UML diagrams and the like.  This is just one simple example of living documentation in practice.  Automation can be applied to more than just code.  Applied properly, automation can keep us doing the things we love while minimizing those tasks we don’t enjoy.  Documentation can be quite useful, but it needs some TLC.  Automating this gives us the best of both worlds.

Leave a Reply

Your email address will not be published. Required fields are marked *