3 ms·
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 ha
by 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 agoI 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 agoGroup them by topic. “Version control incantations”. “Writing and running tests.” “Debugging.” “Deploys.” “Production troubleshooting.” Etc.
- cborenstein 8y agothat'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 agoEach 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 agovery 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 agoYeah, 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 agovery 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 agoI'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.