Understanding Documentation
Podcast: Play in new window | Download (60.0MB) | Embed
Subscribe: Apple Podcasts | Spotify | Email | RSS | More
It’s tricky to get developers to write and maintain good documentation. Frequently, documentation has huge gaps in content, is woefully out of date, contradicts itself, or is simply impossible to navigate. Like writing code, putting together a useful set of documentation is not a natural talent, but is an acquired skill, usually built over long periods of time. Most of the time, the way you learn this stuff is either by screwing up, or by observing when other people screw up.
Like your codebase, your documentation often has to be maintained, occasionally has to be refactored, and needs to be annotated well so that both you and your users can navigate it effectively. Further, you’ll have to make sure that your approach to documentation works well with a variety of use cases, plays nicely with the software development life cycle, and provides methods of feedback that help you make it better.
Good documentation is almost a requirement for a serviceable product. Your users, support, marketing, and sales staff are going to rightfully expect that either your software is going to have decent documentation that stays up to date, or that they can bug you whenever they need you. In short, if you value your sanity, documentation should be your priority.
Episode Breakdown
Some reasonable base assumptions.
Auto-generated documentation is almost useless, except for a few narrow cases. Outdated documentation is worse than useless. Documentation that can’t be navigated won’t be used. Having no feedback loop in your documentation is like not having error reporting.
Consider your audience. There are lots of them.
Other developers inside your organization need documentation to figure out how pieces of the system work. Management needs documentation so that they can explain things to their management and for planning. People looking to buy your software need documentation to determine whether it meets their needs. Your support staff need documentation so that they can troubleshoot common issues. QA needs documentation to make sure that software continues to meet specifications as expected by the user. Your actual users need documentation because they are using your software. If your documentation is online, it needs to be built with google in mind, because that’s the main way people will find solutions to their problems. People looking to integrate with your software need documentation to figure out the best way to integrate with your software and what value an integration might provide to their company. Potential business partners, or buyers of your company need to be able to look at documentation to figure out where your company’s strategy and theirs link up. Tech support people at other companies may need to read your documentation as well, especially if they are helping their own users troubleshoot. Your own salespeople may need your documentation to answer sales questions. People looking to get hired at your company may want your documentation so they can see if they would be a good fit.
Consider your medium/media. The way you deal with content is different.
Hyperlinked text is handy for relatively structured digging through documentation, but it can be annoying when trying to explain best practices or show something visually. Printed manuals. Some clients aren’t in environments where connecting to the internet is a good option. API documentation with samples. Other developers will need this to work with your systems. It may need to be tailored to a variety of programming languages in addition to human ones. Video documentation may be needed to show how to do common operations in your software so that you don’t have to train every single future user. Built-in help is useful for the user while they are in the application. It’s used to show how the screen they are looking at right now works. You will probably need multiple formats in multiple languages. The world is not monolinguistic and never has been. You’re going to have to keep documentation in sync for any supported languages and you need to write in a way that is both clear and not awkward. Automated translation will not help you here.
Consider your development cycle.
Documentation has to keep up with released feature sets. Documentation may have to support multiple features. You may need to control documentation with the same feature flags used in your app. You’re also going to have to have some way of knowing what has changed in your app, so that documentation can be updated. Your documentation team is going to have to write the documentation fairly early in your process, or they will be a bottleneck.
Consider maintenance and reorganization.
Written works have to be reorganized and edited over time, just like code. Like code, when documentation is being reorganized, there are points at which you can’t ship, because things are horribly broken. These will not coincide with the times when the same things are true of the app. You are going to have to periodically adjust wording in your documentation, both to match what marketing says, and what your application does. If you are making major structural changes to your documentation while active development is going on, you may have to gate these changes with feature flags.
Tying code and documentation together.
You are going to spend a lot of time trying to keep your documentation in sync with your code. You are going to want to automate at least some of that, and you’re going to depend on developers for that. This means that developers can screw up the documentation process and/or get blamed for it. Which means politics will be in the mix. Sometimes tiny changes in code will result in huge changes in documentation as well. Don’t expect the people estimating the scope of code changes to have a clue how much documentation will be required to change.
Your writing workflow is important.
Just like with code, you need to have a peer review / pull request / whatever process, in addition to editing. Editing helps you find grammar errors, spelling errors, and the like. Editing typically does not handle the larger structure of the work, especially in regards to things like searchability, link structures, etc. Anyone writing documentation will require as much structure as anyone writing code. You are also going to have to try and overcome Conway’s law, just like developers, because it will reflect in your work as well. Source control and change control are probably going to need to be tied to developer/QA source control and change control, while being kept separate enough so that each group can make good decisions.
Mixing generated documentation with written documentation.
To some degree, you can generate some parts of your documentation. However, generated documentation tends to be low value. If you do generate documentation, even just for developers, you need to have a clean way of mixing non-generated documentation in there to make it useful. A lot of developers don’t seem to understand this, but most people reading documentation do not care how the pieces of your system fit together. They are trying to fit your system into theirs. Intermixing lots of documentation into systems that developers maintain means that either developers will be responsible for those documents (bad) or that those documents will decline rapidly in quality over time (worse). If you do mix some generated documentation with manually-produced documentation, you are going to need to review the manually produced documents any time the automated ones change.
User and organization-specific documentation
You many need to segment your documentation based on what permissions a user has. You may need to do the same per organization, if your software is configurable or has components that can be purchased separately. Your marketing team is going to want to be involved in writing this documentation as well, as it’s a great place to up-sell clients on potential additional features. You are going to have to “test” your documentation from the perspective of a variety of users to make sure that the information that needs to be out there for each use case actually is out there and working. The way marketing segments the product and the way development segments the product will both play into the structure of your documentation, meaning that you’ll be the go-between in many cases.
Documentation security concerns
If your documentation is public, it can be misused. If it’s not public and you need authentication to get into it, you just expanded your security surface area. Be really careful to redact anything from your documentation that has usernames, passwords, sensitive ids (including in URLs), names of clients, etc. One potential user role that you should consider is that of a hostile user conducting industrial espionage and trying to reverse engineer your app, cause security problems, or poach employees/clients/strategic partners. You also need to be careful about accidental early disclosure of information. If your company is planning some huge move that they want to keep quiet, it’s very bad if that leaks out through your documentation. Be careful about how you deal with user-generated input that shows back up in your documentation. A malicious user can do a lot of damage to your customer base through poor security in your documentation system.
Secondary considerations
Putting an emphasis on documentation in your organization is going to change the way you do things. Depending on the type of documentation required, this can often pressure developers to make things more simple than they should be. It can make design decisions political (they are anyway). Good documentation can often help your marketing and sales teams considerably, especially if your documentation is publicly accessible. While this is good, it may increase load faster than you think. Good documentation can also keep your support team out of your hair for smaller issues, making it less likely that you’ll get interrupted. You probably will see at least some releases delayed by documentation and training considerations, just like QA considerations delay things once you get a real QA team. It’s important to figure out who is in charge of the documentation team. This has a high likelihood of getting political if not done carefully.
Book Club
The 17 Essential Qualities of a Team Player
John C. Maxwell
This week we are looking at the fourth quality: Communication. “The team is many voices with a single heart.” In this chapter Maxwell starts with a story about the real life team from the movie Remember the Titans. He tells how the coach integrated the team by making them communicate with one another. A team doesn’t exist without communication, all you’ll get is a group of individuals. Maybe they are working toward the same goals, maybe not. Maxwell gives 5 rules for improving effective team communication. Don’t let them isolate themselves or group off within the team. Make it easy for teammates to communicate with each other. If two teammates have any sort of disagreement, do not let 24 hours pass without addressing it. Give special attention to particularly difficult relationships. Make sure that all important communication is in writing and documented. He also provides three tips for improving your own communication: be candid, be quick, and be inclusive.
Tricks of the Trade
Nothing changes in a modern, professional development environment without changing tons of other stuff around. Don’t feel bad when you get surprised by complexity – you can only plan things with the expectation of some “unknown unknowns”. There is no other kind of planning that works.