Know two things for certain:No one who reads your documentation will have a clue how your shit operates. This includes yourself in five years. Be kind to yourself. State the obvious. Start from first principles. Narrate. Why is there a random 10Gbps switch in this room? There's a story there. Don't be afraid to capture it.Everyone who reads your documentation is currently fucked. They are at the "where are the docs" stage because they have already tried everything they know. They may also be time-sensitive fucked. Recall, this might also be you. Frontload the documentation with an executive summary. Try to solve the most common program you envision in the first line. Don't bury it on page 9 with no pointer to it from someone starting at page 1. I like to put a section just after my TOC called "Field Notes" which is expected to be updated over time, and I preload these field notes with all the weirdness inherent in the system that I see causing a problem later.Your core responsibility, in other words, is to un-fuck someone who doesn't have a clue how your shit operates. I think if you build your docs with those two points in mind, whatever you produce will be effective, if not wholly "proper."
- No location available
-

There is this saying about learning to code, there are two stages:Learn to code aloneLearn to code in a teamSome people never get to stage two. I think the same can be applied to documentation. But there is one more stage:0. Having no documentationHaving documentation for yourself onlyHaving documentation suitable for the team.
- No location available
- documentation,

Know two things for certain:No one who reads your documentation will have a clue how your shit operates. This includes yourself in five years. Be kind to yourself. State the obvious. Start from first principles. Narrate. Why is there a random 10Gbps switch in this room? There's a story there. Don't be afraid to capture it.Everyone who reads your documentation is currently fucked. They are at the "where are the docs" stage because they have already tried everything they know. They may also be time-sensitive fucked. Recall, this might also be you. Frontload the documentation with an executive summary. Try to solve the most common program you envision in the first line. Don't bury it on page 9 with no pointer to it from someone starting at page 1. I like to put a section just after my TOC called "Field Notes" which is expected to be updated over time, and I preload these field notes with all the weirdness inherent in the system that I see causing a problem later.Your core responsibility, in other words, is to un-fuck someone who doesn't have a clue how your shit operates. I think if you build your docs with those two points in mind, whatever you produce will be effective, if not wholly "proper."
- No location available
-

There is this saying about learning to code, there are two stages:Learn to code aloneLearn to code in a teamSome people never get to stage two. I think the same can be applied to documentation. But there is one more stage:0. Having no documentationHaving documentation for yourself onlyHaving documentation suitable for the team.
- No location available
- documentation,