4 ms·

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 your

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.

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.