3 ms·

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 str

• 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.