Documentation, good or bad?
Throughout my day, I work with a variety of software and SDKs. The quality of documentation varies, some are well-documented, while others offer little to no guidance. Often, the ones with minimal documentation operate under the assumption that providing an SDK alone is sufficient.
Companies that offer extensive documentation generally fall into two categories: useful and useless. You might wonder how extensive documentation could be useless. Here’s my perspective on what makes documentation valuable:
- Documentation that exists just for the sake of it is ineffective.
- Documentation should serve a clear purpose.
- Documentation should help me, as the customer, achieve my goals.
- Examples are your friend.
For example, telling me that a field provides information about a device’s status is helpful. However, if I need to decipher what each of the five or more possible values are, then the documentation has failed its purpose.
When writing documentation, whether it’s for internal use or for your customers, it’s crucial to understand your audience. Remember that people need to rely on your documentation, and they don’t want to waste time trying to decipher it.
