Do you write documentations?
Yes, a lot. I do a lot of work on UI libraries and other things with APIs. For projects like that, anything you don't document may as well not exist at all. For other projects, I'm regularly documenting onboarding/setup guides so people (or just me in a year) can easily learn how to get the project up and running.
What role do you think documentations play in writing good code/software?
They reduce risk, increase developer engagement... basically good docs make for a happy team.
What are the best practices you've seen/heard/used in writing documentations?
- Be concise - write just enough
- Write without assumptions - write a document that someone could follow without needing help
- If you do make assumptions, declare what they are (eg. I often state prerequisites for installation guides)
- Treat docs like code - DRY and YAGNI both apply surprisingly well. Docs can be modular!
- Think about the maintainability of your docs - don't set yourself up for an impossible task
What are you trying to avoid in documentation? (bad practices? common mis-conceptions?)
- Unmaintained or innacurate docs are harmful
- Unmaintained or innacurate docs are REALLY harmful
- No one tool is the best for all documentation - eg. I use a mix of wiki (Confluence), markdown files in repos (readmes) and purpose-built documentation websites. I don't use much auto-generated documentation as I find it tends to be less useful. In the end though, the tool your team will happily use and maintain is the right tool.