Article type: Fundamental
Article name: Axiome - Documentation Roles
Author: Framez


Description:

Writing good documentation is surprisingly difficult. Even large companies with dedicated technical writers often struggle to keep their documentation clear, complete, and up to date. For open source developers, the challenge is even greater. You’re deeply familiar with the project, which makes it easy to skip over things that seem “obvious” but aren’t to someone new.

Another problem is not knowing who you’re writing for. Is the reader a curious user? A system administrator? A developer looking to contribute? Each of them needs different information, different terminology, and a different level of detail.

One possible solution is to introduce documentation roles. Instead of a single one-size-fits-all view, readers could switch between User, Administrator, and Developer perspectives. The documentation could even be color-coded, making it immediately obvious which audience a page is written for. The same project, viewed through three different lenses.



Back