3 ms·

Every so often I'll see something like this on HN that suggests that software engineers should be keeping similar records of everything they do, if for no other

Every so often I'll see something like this on HN that suggests that software engineers should be keeping similar records of everything they do, if for no other reason than to have a record of problems they've solved that can be grepped when a similar problem shows up. This seems like a good idea. I wish I could be bothered to actually do it though

cratermoon 5y ago
Every time you look up something on StackOverflow, refer to the API docs, or refer back to the ticket, use case, or requirements document, make a note of your question and the answer. Even when you just stop typing to take a break, note down where you are and what you just did. Every time you think you need a TODO comment, make a note instead, or also. Consider Kent’s Beck’s recommendation to write down every decision you make. Some other views https://shannoncrabill.com/blog/taking-notes-as-a-developer/ https://shannoncrabill.com/blog/taking-notes-as-a-developer/ https://blogs.oracle.com/javamagazine/post/take-notes-as-you-codelots-of-em https://blogs.oracle.com/javamagazine/post/take-notes-as-you...
- lexicality 5y ago
  I know all of this, but it's still a lot of effort that I'm apparently not willing to go to. However I do at least partially do this. Whenever I use SO, I put a link to the answer in a comment next to the code that implemented it. Whenever a ticket or API doc requires doing weird stuff, I put a link to that too. Whenever I make decisions that might be slightly weird, I put a couple of paragraphs in the git commit. Not the same, but still better than nothing I guess
  - cratermoon 5y ago
    > it's still a lot of effort that I'm apparently not willing to go to. Just like any habit, you have to start doing it, build up, and make it so you can't not do it. It's not about discipline, it's about routine.
NineStarPoint 5y ago
As an ops person/SRE, I can say that pretty much every person I know in this space ends up with these sorts of journals of things they’ve seen go wrong. The really useful, and harder, part is getting everyone to put them in a public area so you can go off of other people’s experiences as well. Having everyone’s barely-documented garbled mess of previous experiences can sometimes be a life saver.

cratermoon 5y ago

Every time you look up something on StackOverflow, refer to the API docs, or refer back to the ticket, use case, or requirements document, make a note of your question and the answer. Even when you just stop typing to take a break, note down where you are and what you just did. Every time you think you need a TODO comment, make a note instead, or also. Consider Kent’s Beck’s recommendation to write down every decision you make. Some other views https://shannoncrabill.com/blog/taking-notes-as-a-developer/ https://shannoncrabill.com/blog/taking-notes-as-a-developer/ https://blogs.oracle.com/javamagazine/post/take-notes-as-you-codelots-of-em https://blogs.oracle.com/javamagazine/post/take-notes-as-you...

lexicality 5y ago
I know all of this, but it's still a lot of effort that I'm apparently not willing to go to. However I do at least partially do this. Whenever I use SO, I put a link to the answer in a comment next to the code that implemented it. Whenever a ticket or API doc requires doing weird stuff, I put a link to that too. Whenever I make decisions that might be slightly weird, I put a couple of paragraphs in the git commit. Not the same, but still better than nothing I guess
- cratermoon 5y ago
  > it's still a lot of effort that I'm apparently not willing to go to. Just like any habit, you have to start doing it, build up, and make it so you can't not do it. It's not about discipline, it's about routine.

NineStarPoint 5y ago

As an ops person/SRE, I can say that pretty much every person I know in this space ends up with these sorts of journals of things they’ve seen go wrong. The really useful, and harder, part is getting everyone to put them in a public area so you can go off of other people’s experiences as well. Having everyone’s barely-documented garbled mess of previous experiences can sometimes be a life saver.