While I think there is great benefit in using concise and clear language, I highly disagree if anyone takes away the idea their documentation should be a themed

While I think there is great benefit in using concise and clear language, I highly disagree if anyone takes away the idea their documentation should be a themed after an RFC (I do enjoy reading RFCs though!) This [0] was imo an excellent discussion on documentation that gets to the issue much more than word and formatting choices. The short is there isn’t “documentation” as one thing, but four. 1. Tutorials where you start to finish explain it to a newbie, 2. How to guides where you explain specific tasks, 3. Discussions where you lose all formal pretext and explain your INTENT (huge) and reasoning for decisions, like you would actually explain to a person, not a robot, not some cute marketing talk 4. Technical reference that goes over the actual mechanics and the weeds that people need only once they’re working with your solution. It was on HN at least once. [0] https://www.divio.com/blog/documentation/ https://www.divio.com/blog/documentation/