4 ms·

Ask HN: When should my team start documenting?

• phendrenad2 8y ago
  When you do the same thing more than once ever, document it. So if in the first minute that your startup exists you do something twice, document it. 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.
  • cborenstein 8y ago
    I like that simple rule but I think it will lead us to have a lot of small notes super quickly, which might be difficult to weed through later. Do you find yourself with this problem? 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?
    • cimmanom 8y ago
      Group them by topic. “Version control incantations”. “Writing and running tests.” “Debugging.” “Deploys.” “Production troubleshooting.” Etc.
      • cborenstein 8y ago
        that's a good idea. would you recommend a file/directory structure or just tags/keywords next to each command in a flat file? I'm wondering if the directory structure will feel too clunky and result in less getting written down.
        • cimmanom 8y ago
          Each of the categories above would be one file. 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.
          • cborenstein 8y ago
            very interesting - that seems like a good and still pretty simple rule too. I feel like if the docs are organized well then volume shouldn't matter but at the same time having fewer docs means less room for error in organizing.
  • d_jordan 8y ago
    Yeah, that's what I like to do as well. If it's something that I know I'm going to do a few times, and I don't remember the process off the top of my head the second time I'm doing it, write it down. I like to keep notes for things I do day to day and revisit my notes at the end of the week to try and find time to flesh them out a bit more and start organising.
    • cborenstein 8y ago
      very interesting. It seems like a good idea to not worry about the structure when first writing things down but to reserve time at the end of the week to organize. where do you usually write your "temp" notes? do you use any structure or not until the end of the week?
      • d_jordan 8y ago
        I'll usually use something like oneNote, I find its folder structure really handy for note editing because it kind of forces the user to organise as you go. I'll try and make the note as detailed as I can as well because that'll give more context about whether or not it's project specific, or more generic, which makes it a little easier to classify at the end of the week.
• s12345 8y ago
  I've found documentation on commands for running tests, running scripts, and running other manual processes useful even if I've run the commands before many times, and even if I was the one who created the commands. Documenting anything you find yourself looking up a lot online, or in your Terminal history would probably be useful even at the beginning just to reference for myself. 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?
  • cborenstein 8y ago
    thanks for sharing - that makes sense. Where do you usually write your runbooks? In a google docs/confluence type wiki or with your code? How do you organize them so that you can find/share them quickly?
    • s12345 8y ago
      We write our runbooks in a wiki in Phabricator. We have a wiki per topic-- we have one for getting started with the system that has some useful commands for running tests, another for deploying the system, etc. I usually find them by searching for terms that I remember are in them, but starting out, I was sent some of the wiki pages.
• cimmanom 8y ago
  Top priorities for documentation: how to set up a production environment; how to get up a working copy running from scratch; any arcane command-line incantations or click sequences that you have to look up (or worse, work out by trial and error) more than twice. Document these from the get-go. In an emergency you’ll be glad you have them, and the next person you onboard will be grateful. 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.
  • cborenstein 8y ago
    thanks for all of your suggestions. What do you find is the best way to organize the command-line incantations (what a great way to describe them) and click sequences? do you write them in something like google docs or confluence or in your code?
    • cimmanom 8y ago
      Any of the above will work as long as everything’s well organized and easy to find. 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.
• ab_io 8y ago
  Ideally, from the get-go. Your system and documentation should be produced & grow in-parallel. At worst, before any team members with key (undocumented) domain knowledge leave.