Different types of user require different documentation.
The person using your web API or your library needs to know "if I call this with these parameters this will happen" and also "to do this I need to call this with these parameters". These are two different views of the same information, of course, but found in different ways. I've found Stripe's online API doco to be an example of this done right, and exim's configuration doco to be an example of this done horribly horribly wrong.
In the mean time the person maintaining your code - whether that be you in a few months time or your colleagues - needs something different. They need a quickly accessible overview of the whole system and how everything interacts, what the private functions not exposed to the users do, where they are called from, how it is all tested, how it is deployed, and so on. For the overview I recently discovered PlantUML's sequence diagrams, which a colleague used for the overview of a system that talked to numerous third parties as well as talking to our other internal systems and having plenty of its own internal state. It beautifully summarised a year and a half of work in one simple diagram and was infinitely superior to the version I had produced earlier in a vector graphics package.
Don't forget to commit all your doco to version control, including the source code for diagrams, and to include pointers in doco/diagrams to code and vice versa so that you stand at least a small chance of keeping them in sync!
If you have the budget, hire a technical writer/librarian to help you make your documentation discoverable. All too often your company will have plenty of documentation written over a period of years which most people know exists but they have no idea how to find it because it was all written by individuals who thought they knew the perfect place to put it in your wiki, or it's attached to just whatever random ticket inspired its creation, or it's in the workspace of a team that broke up a decade ago.
Wow, this is a really detailed comment. Thank you for that! I think it adds another view on this subject and shows that documentation, while seems very simple, is indeed a difficult topic! I will encourage every viewer of this article to also dive deeper into the concept you mentioned 🙂
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Different types of user require different documentation.
The person using your web API or your library needs to know "if I call this with these parameters this will happen" and also "to do this I need to call this with these parameters". These are two different views of the same information, of course, but found in different ways. I've found Stripe's online API doco to be an example of this done right, and exim's configuration doco to be an example of this done horribly horribly wrong.
In the mean time the person maintaining your code - whether that be you in a few months time or your colleagues - needs something different. They need a quickly accessible overview of the whole system and how everything interacts, what the private functions not exposed to the users do, where they are called from, how it is all tested, how it is deployed, and so on. For the overview I recently discovered PlantUML's sequence diagrams, which a colleague used for the overview of a system that talked to numerous third parties as well as talking to our other internal systems and having plenty of its own internal state. It beautifully summarised a year and a half of work in one simple diagram and was infinitely superior to the version I had produced earlier in a vector graphics package.
Don't forget to commit all your doco to version control, including the source code for diagrams, and to include pointers in doco/diagrams to code and vice versa so that you stand at least a small chance of keeping them in sync!
If you have the budget, hire a technical writer/librarian to help you make your documentation discoverable. All too often your company will have plenty of documentation written over a period of years which most people know exists but they have no idea how to find it because it was all written by individuals who thought they knew the perfect place to put it in your wiki, or it's attached to just whatever random ticket inspired its creation, or it's in the workspace of a team that broke up a decade ago.
Wow, this is a really detailed comment. Thank you for that! I think it adds another view on this subject and shows that documentation, while seems very simple, is indeed a difficult topic! I will encourage every viewer of this article to also dive deeper into the concept you mentioned 🙂