On documentation
published on 2023/12/28
Docs should use small words to describe big ideas - so don't use flourishy words or complex sentences to describe what can be said in simpler terms. You will lose users along the way and it isn't worth your writer's ego.
Docs should tell a story when you can - because a personal, relatable set of tasks that tell a tale will be more engaging and memorable for your user than an abstract set of instructions.
Docs should be searchable - because seriously: this is a no-brainer. If your docs are not easy to find stuff in, your users won't find what they need.
Docs are almost always part of a larger strategy - and this is especially true when it comes to software products. This touches on the larger topic of developer advocacy, but in short: your docs should be supported by video tutorials, real use examples, and live technical support.
Docs should be tested - because you may be sure that everything is right, but without real users, like with any other product, you won't know for certain. Test it and test it again.