“It’s a Feature” - Documenting Known Issues and Product Shortcomings¶
Description
Imagine for a moment that documentation is the face of your product. How much concealer would you put on it?
The majority of people would likely agree that no product is ever perfect. When it comes to software, the jokes about bugs practically write themselves. Should the product documentation acknowledge this, or should it cover up the imperfections? In some cases, the answer seems obvious, but what about those situations where there is a major known issue - or five? How should the person in charge of documentation address this? Should they just stick a big warning into the release notes, or point out the problem and offer a quick workaround in the documentation itself?
This is not only a content issue, but also a question of ethics. It is a challenge that has come up time and again in my personal (albeit short) career as a technical writer, and I suspect many others have faced it, too.
This talk will look at some strategies that writers can rely on if they decide this is an issue worth considering. Important aspects that will be covered include:
- the tone and language used when addressing product shortcomings
- communication with stakeholders, product managers and other subject-matter experts
- dealing with clunky or unintuitive UIs and workflows that are not officially recognized as issues, but are still impeding the user experience and understanding of the product
- Conference: Write the Docs Prague
- Year: 2018
