I can’t count the number of times my notes have saved me or my team some serious grief. I don’t have to keep everything in my head. I can offload my brain into notes.
Godspeed, but there’s no way I’d give any of that up.
Godspeed, but there’s no way I’d give any of that up.
I'm not big on note taking myself, but when I do, the things I capture is very different from the version I put into the official documentation.
There is a good article: A rational design process, how and why to fake it.[1] Basically how we reach our goal and how we present them are two different things. The personal notes have the details on failures, wrong turns and alternative ideas, the official documentation won't have that.
1) https://www.cs.tufts.edu/~nr/cs257/archive/david-parnas/fake...
To build upon this point, there's a problem that writing docs is a thankless job: those who benefit from it do so silently, whereas those who selflessly shared notes later can find themselves involved in issues they have no involvement.
It's a lose-lose situation.
I'd love to have a universal shared notes system for the whole team, but it's proven unrealistic when seeing how things work over decades.
With my former team I wrote 90% of the documentation. A while after I left they had to migrate their docs to a new system, and used it as an opportunity to clean up. I went back to try and reference a 20 page doc I wrote, going very in depth on a topic during a period where I was deep into it. Gone. I wish I had kept my own copies instead of relying on the shared platform. There was still a lot of good and relevant information in that document, but the people going through it lacked the knowledge and context to see it. There have been many examples like this.
There are also things that don't seem like they deserve a note in a formal system. One day thing X broke and we found out we had to talk to person Y to fix it. No one else thought to write it down, but I did. It broke again yesterday, and I was able to quickly bring up the name of who to talk to, while everyone else just tried to remember and hunted through their chat history. Search of my local notes (in Obsidian) works much better than Confluence. The low friction also means it's easy to drop stuff in, even if it might not be that useful. The friction on Confluence is higher. I tried keeping all my notes in there once, so I could easily share them with others if/when needed, but it was too much effort, and only a matter of time before it goes away and we move to something else (that's happening to some degree right now).
a) how can you tell some random note you took today is critical project documentation?
b) why do you believe people read through project documentation?