hckrnws

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.

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.

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.

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.

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

+1

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.

- 1:1 meeting note: there's a built-in building block support in Google Docs: https://youtu.be/S1ef5vvMT2k

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

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?

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

I might not be the target audience, but this screams corporate junk

I thought the same (“corporate junk”) early in my career... then I had to start getting dozens/hundreds of people to execute in a coordinated fashion against a defensible plan...

Some comments in this thread make me take for granted how junior people are, some of this stuff is table stakes big co stuff and sometimes not even enough, you make these docs that answer everyones questions but maybe 2 out of the 12 people who should know actually read it

:) one man's treasure