"Asking me what’s my favourite documentation is a bit like asking me what are the best doorways I’ve crossed in my life. We remember places, not open doors; we recall the things we did through software, not great docs. In my case, I seldom remember good or great documentation because its purpose is not to get in the way. On the other hand, I do remember lots of bad documentation when it failed to provide answers. The curse of technical writing is that the best expressions of our work are the ones people rarely notice, because they offer so little friction they never disturb the user’s flow.

There are exceptions to this, of course. The first is documentation that is presented in such a way that it generates a “Wow” moment. Perhaps it’s a code snippet you can run, an interactive demo, or similar gimmicks. While they’re not key to great documentation, they make for some memorable experiences, though that can backfire quickly if the docs aren’t good. The other exception are docs that teach us something new, either through conceptual explanations or examples. Some of the best docs I’ve read are aware that they’re also teaching new ideas and concepts. You can tell because they grin."

https://passo.uno/my-favorite-tech-docs/

#TechnicalWriting #SoftwareDocumentation #Docs #DocsAsCode #SoftwareDevelopment