Ask HN: When should my team start documenting?
When did you start writing documentation for your startup? How did you decide it was time to start? What were the first things you documented?
Edit: I have to add this because I think I'll be misunderstood otherwise... People tend to think of documentation as an all-or-nothing deal. Documentation can be as simple as a README.md with "npm start" (or whatever the invocation command for the app is) in it. Documentation doesn't need to have structure or award-winning prose right off the bat. It doesn't need a table of contents or a glossary. Just dump your thoughts on the project into a text file, and refactor later.
How do you make the small commands findable/understandable while minimizing time spent on docs? When do you refactor and what does that look like?
Each command should have a sentence or two of context, which also helps with searching: “If the Baz starts showing symptoms of Quux, frobnicate the Foo to reset the Bar: <insert command here>”.
You can use headings to separate out DB admin incantations from server admin incantations from system admin incantationss, etc.
If something accumulates thousands of lines of notes or explanation, just carve off a doc for a subtopic, or create a subdirectory with files for multiple subtopics.
Edited to add: I don’t subscribe to the idea of documenting every single thing you do more than once. I set a slightly higher bar of anything you have to look up (or ask someone or that someone asks you) more than twice. That tends to work as a decent filter for obvious vs. requiring documentation, and keeps the volume of docs under control. As time goes on and your team grows, of course the set of items meeting those criteria will grow, but only at the pace where they become valuable.
Second level priorities: complex algorithms; counterintuitive design decisions; complex high-level business logic, especially logic that’s spread across multiple methods/classes/modules. These are useful even for a solo developer if you end up stepping away from that area of the code for more than a month at a time. Once your team is big enough that people are regularly editing parts of the codebase that someone else wrote (or that depend on code someone else wrote) having this can save you hours of developer time per week.
Middling priority: documentation for HTTP APIs (and any other inter-process communication APIs). If you can auto-generate as much of this as possible, do so. I haven’t found it useful enough to put time into writing manually for a team of <15, but this is also on the hours per week list if the people consuming the APIs weren’t involved in writing or designing them.
Lowest priority: doc blocks and internal API documentation. Generally your developers can work this stuff out on their own. Depending on your language, API docs with function signatures may be auto-generatable, though the utility is limited if your developers are already using IDEs and other tools that provide autocomplete and lookups. Doc blocks with function descriptions are useful if the function does something unintuitive or too complex to be described in the name and should be written as part of general commenting practice as a matter of course.
Personally I find Google Docs and Confluence impossible to locate stuff in. Markdown docs within your main repository (or a central docs repository if for some reason you have tons of repos, though IMO that’s an antipattern for a small team) should work fine at least for a team or up to 20 or so.
As time goes on and the company grows, I think reasoning becomes useful to document. Why were technical decisions made in code changes, why were tasks deprioritized, why did tasks grow in scope or reduce in scope over time?