I looked through about 8 of these templates before feeling the need to stop. While the content is mostly solid, the design and layout make them hard to use in practice.
I really appreciate the effort behind this, but they could benefit from a design pass to make them more usable and visually coherent.
Sam_Odio · 6h ago
Interesting - these have exactly the design polish I'd expect from working at FB, Twitter, DBX, etc... From what I've seen most of the people I've worked with at those companies care more about the quality of my thinking than the polish of my docs.
Paul - great work. Was thinking of doing the same. I'd love to collaborate on some sort of shared resource/repo of docs like these (github?) and contribute a few of my own.
pedalpete · 6h ago
I don't know why you're getting down voted, this is an absolutely apt comment.
A shared repo on github would be great! I was wondering....where am I going to bookmark this so I'll remember to go back to it in the future. Though, how many of the people who would benefit most from these docs don't use git?
Though I may copy the docs into a confluence template.
pkoullick92 · 5h ago
Yeah, love that Sam. I'm not much a github user myself but if there's some existing body of best-in-class templates I'd love to be a part of that. For me, it's all about having a quick thing bookmarked that I can just duplicate from.
yegle · 5h ago
Nit:
- Decision doc: It'll be great to have a "Stakeholders" section listing each stake holders' name , and they can add their concerns in that section to start discussion.
- Investigation doc: There should be a "things we tried so far" section listing the actions took to validate each hypothesis, and the outcome of those actions, in timeline order.
I don't disagree outright, but every time I read something like this it's obvious that it doesnt come from experiential success in the relevant area, just kind of a vibe about how things should be done, without tangible proof. IE the legendary Dropbox analysis on here. Never in my professional career have I cared about anything you listed here
Rastonbury · 16m ago
Wait have you never had a work experience where people make decision without properly asking around then someone on another team chimes in to say actually you missed X. Or you tried to fix something or an incident but have to read through a slack thread to figure out what's been tried? These seem like common work scenarios at most places
yegle · 4h ago
Except for the last one, the other two are from my experiences needing to write those docs.
For decision doc, do you prefer tracking stakeholders comments scattered in multiple places (and also track down the closed comments), or have a single places to read their concerns and address them explicitly as part of the decision making process?
For investigation doc, have you not had the need to hand off to someone else, maybe because you need to go on vacation, or you need to hand off to a colleague in a different time zone? How does the one who took over know what was done for a line "we investigated this hypothesis and it didn't work"? What if the action taken to validate the hypothesis is not comprehensive or the conclusion from the actions is not correct?
farceSpherule · 7h ago
If only people would document... When I was a SW Eng Mgr, I had to stop approving commits/deploys because engs would not do something as simple as javadoc.
Once people started missing deliverables and having their comp and ratings impacted, documentation shot to 100%.
I really appreciate the effort behind this, but they could benefit from a design pass to make them more usable and visually coherent.
Paul - great work. Was thinking of doing the same. I'd love to collaborate on some sort of shared resource/repo of docs like these (github?) and contribute a few of my own.
A shared repo on github would be great! I was wondering....where am I going to bookmark this so I'll remember to go back to it in the future. Though, how many of the people who would benefit most from these docs don't use git?
Though I may copy the docs into a confluence template.
- Decision doc: It'll be great to have a "Stakeholders" section listing each stake holders' name , and they can add their concerns in that section to start discussion.
- Investigation doc: There should be a "things we tried so far" section listing the actions took to validate each hypothesis, and the outcome of those actions, in timeline order.
- 1:1 meeting note: there's a built-in building block support in Google Docs: https://youtu.be/S1ef5vvMT2k
For decision doc, do you prefer tracking stakeholders comments scattered in multiple places (and also track down the closed comments), or have a single places to read their concerns and address them explicitly as part of the decision making process?
For investigation doc, have you not had the need to hand off to someone else, maybe because you need to go on vacation, or you need to hand off to a colleague in a different time zone? How does the one who took over know what was done for a line "we investigated this hypothesis and it didn't work"? What if the action taken to validate the hypothesis is not comprehensive or the conclusion from the actions is not correct?
Once people started missing deliverables and having their comp and ratings impacted, documentation shot to 100%.