Miguel Afonso Caetano on Nostr: “Don’t cover all the details of the product and the technologies it relies on ...
“Don’t cover all the details of the product and the technologies it relies on because no one reads the documentation anyway, right?”
WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.
When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack.
A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way.
The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core.
https://books.google.pt/books?id=f7M1DwAAQBAJ
#TechnicalWriting #SoftwareDocumentation #Documentation #TechnicalCommunication
WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.
When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack.
A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way.
The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core.
https://books.google.pt/books?id=f7M1DwAAQBAJ
#TechnicalWriting #SoftwareDocumentation #Documentation #TechnicalCommunication