Ask HN: How does your organization handle documentation?

6 points by niklearnstodev 4 years ago | 1 comment

It seems useful to get a sense of how different organizations handle documentation in the real world. I'm curious whether your org uses the following types of documentation (or any others) and how they manage it, with whatever details you can give:

-Developer setup

-Developer best practices & style

-Product documentation

-Project documentation

-Docblocks/doc strings

-Inline comments

More importantly, what are the habits that your org encourages around documentation?

niklearnstodev 4 years ago |

My org (small but growing team, web) manages developer setup, product and project documentation in Notion, and the docs often get created but not maintained, and the product documentation is mostly for recently developed segments of the app. Commenting is generally avoided in favour of clear, self-documenting code, with more complex methods warranting doc strings. We do not add a comment for every method and their parameters/returned values. Inline code is only used for complex segments of code.

Overall, I feel that our codebase is well-documented, but our product and projects could use better documentation to help new team members and people seeing a segment of the product for the first time in a while. I'm unsure as to where this should live, however.