Once you’ve released your standalone app to the world, someone else will want to use it. How will they use it? How will they install it? And does it solve the same kind of problem they have? In this chapter, we’ll look at how you can start addressing the challenge of documenting your standalone app.
Starting with questions
Regardless of what formats and tools you use to document your standalone app, or how you decide to distribute documentation throughout your codebase, all of your documentation should be motivated by answering the questions that someone else – even future you – will have when approaching your standalone app.
Several of the questions you should ask are who will be reading this and what are they trying to do. Most often the “who” will be a developer user, someone who is either assessing whether to use your standalone app or looking for help in integrating it into their project. But it may also be someone else, another project stakeholder trying to assess whether your standalone app should be considered one of the project options.
- 1.
Is this standalone app a good fit for my project?
- 2.
How do I start using it?
- 3.
What is it fully capable of doing?
- 4.
How can I report a bug or get involved?
The first question is about assessment. By assessment I don’t mean ranking or scoring your app for some kind of arbitrary scale, but judging whether someone should use it. This is the broadest and most subjective kind of questioning someone will have looking at your standalone app, and there is no single, surefire way of addressing this question.
However, there are several critical questions you can and should address that go a long way toward helping people assess your app, including (i) answering what problem it solves, (ii) how it solves that problem, and/or (iii) how it solves this problem differently from other solutions.
Django integration with RQ, a Redis-based Python queuing library. Django-RQ is a simple app that allows you to configure your queues in Django’s settings.py and easily use them in your project.
We now know exactly what this is for and what it does. We don’t know how to install it or use it yet, but from only those two sentences, you’ll probably have a fairly good idea as to whether this app will be of help to you.
Once someone has decided to use your app, they’ll next want to know how to start using it. This includes (i) installation, (ii) configuration, and (iii) any subsequent integration or usage steps.
Installation is typically straightforward, including a pip install and adding the app to INSTALLED_APPS, but you should be sure to make explicit the names used here and document any differences from the expected. As to configuration, at a minimum you’ll need to include any changes or additions to project settings (beyond INSTALLED_APPS) that are required, such as MIDDLEWARE additions, and also additions to the project urls.py configuration.
Integration and usage include changes to the user’s own code required to make use of your standalone app and any commands or output that the user should know about. If your standalone app includes mixin classes for views, what attributes or methods should the user be aware of immediately? If it includes management commands, what are they named and what are the required arguments? There is much more you can include, but for immediate answers, questions like this will guide what to include.
Lastly are the questions of how a user can provide feedback or contribute back to the project. It’s easy to take these questions for granted and to think that the answers are self-evident – just create a new issue on the repo of course! – but that’s not always the case and you should make this clear for your users. A simple statement about where to file issues or whether there is an email for asking questions suffices as a start, but you can and should include more guidance, including not just where to record issues but how. This will save your users time and you as well.
The forms of documentation
Documentation should start with a README file. This is a single, top-level text file with or without basic markup formatting (e.g., README.rst or README.md). It describes what your app does and how to install it and configure your project to use it and either includes some basic usage documentation or points to where that can be found. This file is typically the first thing someone will see when they see your app in a public repository, and it’s easy to include the content here in the long_description used by setuptools to include in PyPI. It’s also a long-running convention, so regardless where you include the rest of your docs or how you structure them, someone can expect to find this file at the source root.
Maslow’s hierarchy of needs, illustrated by Wikipedia user FireflySixtySeven (CC BY-SA 4.0)
This hierarchy of needs mimics Maslow’s popular hierarchy of needs, which is intended to illustrate a hierarchy of human needs, whereby the lowest level must be satisfied before those above can be met. Whether or not the psychological theory is true, it’s a useful analogue for approaching documentation.
At the base level come installation and configuration. Without knowing how to actually get your app and what "dials" need to be turned, all the subsequent documentation is of little practical value. Often the README itself will suffice for this purpose, but if the available settings are more than a few, then installation and configuration, or just configuration, may warrant their own section in the documentation.
Subsequent to this is the basic usage and integration described in the preceding section. A handy way to think about this is getting started with your app quickly, and a quickstart is an excellent way of showing how to make practical use of your app without needing to dive into the full documentation. This is usually the bare minimum required to start using the app, from the most commonly used command to a simple practical example integrating your app into another.
For apps that require non-trivial integration, such as building blocks or even additional frameworks, a tutorial on doing so is a valuable next step. A tutorial guides the user through the steps of using software by example with a clearly defined end goal that each step helps achieve. This won’t be necessary for many standalone apps, but for apps with significant features, it is useful for showing how to use the app where a quickstart is insufficient.
As an example, the django-graphene app, a standalone app for adding GraphQL functionality to Django project, uses two such tutorials in its documentation. The basic tutorial guides the user through the typical quickstart steps and then proceeds through creating example models and views in a sample app and even loading provided test data to match the prescribed models. From here the user can actually see how the app works by building a small app and compare the results described in the documentation to the results they see on their own computer.
Whereas tutorials provide a "horizontal" approach to documenting a standalone app by starting with a problem whose example solution includes many different aspects of functionality, API references provide a "vertical" source of documentation, with details that are organized by implementation. The Django docs are largely organized this way. Rather than including tutorials for every type of problem, the Django docs include a basic tutorial and then detailed documentation organized logically by functionality. There is no tutorial on how to create an app that sends out aggregated book ranking information in email reports, but there is detailed documentation about how to use email, how to use Django’s model classes, and about the various database aggregates and expressions.
Lastly, and at the top of our hierarchy, sits the cookbook. As might be expected from the name, cookbook documentation is a collection of recipes, of small real-world examples, that both demonstrate how to use the features of your standalone app and provide a measure of inspiration for how it can be applied. These can be extracted from real use cases or contrived, though they should be useful whether made up or not.
Code comments and docstrings
Many Python programmers are careful to document their code, including comments for "interesting" code blocks; detailed docstrings explaining modules, classes, and functions; and even type hints. Clearly written and well-documented code is a fantastic aid for development, especially for new contributors, and can be an asset for developer users who simply want to better understand the internals of your app. That said, there is a difference between code documentation and usage documentation.
The reasons why include not just how one reads the documentation (see the section “Tools for documentation” ) but organization and level of detail. Simply put, source code isn’t typically organized to answer the questions of why and how when those questions have to do with the problem the app is solving; it’s organized to solve the problem. The entry points are designed for execution and importing, not for reading and browsing. There’s also value in decoupling documentation from source code when that separation makes contributing to the documentation easier.
Be wise about not mistaking code documentation for user or project documentation.
Tools for documentation
Once you have documentation for your standalone app, the next step is to make it readable for potential users without needing to look through source code. Whether you have used reStructuredText or Markdown, there are several tools that will make turning your documentation into web deployable HTML a snap.
The sphinx-quickstart command will guide you through several prompts to help identify where to include the built HTML, basic project information, and the natural language in which docs will be written. The generated Makefile – or make.bat if you’re using Windows – can then be used to read your reStructuredText source files and create browsable and searchable HTML files. You can also build to other formats, including PDF, though this may require additional software, such as LaTeX.
The details of structuring your documentation using Sphinx and reStructuredText are beyond the scope of our discussion here; however, reStructuredText allows you to create rich indexes and also build documentation from your standalone app’s source code.
An alternative to Sphinx for those who strongly prefer using Markdown is MkDocs. What Markdown and MkDocs lack in features, they make up for in simplicity. MkDocs projects are configured using Yaml files instead of Python, and Markdown’s syntax – as well as features – are more stripped down compared to reStructuredText. This can be an asset if you’re working with other people who are already familiar with Markdown. Just like Sphinx, MkDocs will take your documentation source and create browsable, searchable HTML documentation.
Once you have a tool that can turn documentation source into HTML, you’re nearly ready to deploy it so that developer users can browse the documentation online. The simplest way to do this is to simply provide the built HTML over the Web, for example, copying it to a web server, adding to a repository branch to serve using GitHub pages, among others. While this works, it does introduce a lot of manual work.
Instead, you can use Read the Docs to automatically build and host your project documentation. Read the Docs will work with either Sphinx or MkDocs, and provided you are using GitHub, Bitbucket, or GitLab, it will allow you to connect your repository using a project integration to build from repository updates (you can use it with other source code platforms too; however, it will require more manual setup).
Summary
In this chapter, you’ve learned how to get started with user-facing documentation for your standalone app, including what kind of questions to ask in guiding it, forms of documentation suitable for users, and tools for actually deploying documentation.
In the next chapter, we’ll delve into additional topics in testing including testing migrations and how to test against different versions of Python and Django.