22 Comments

really great. Thanks

Expand full comment
Nov 6, 2023Liked by Ryan Peterman

Just to add in your list and am not sure if this is a common doc template but for proposing changes in current system/service/process or for justification of some major decisions there are ADRs doc. I have seen a fair amount of these docs in my current org.

Expand full comment
Nov 7, 2023Liked by Ryan Peterman

But what you have provided is on-point 🔥.

Just thought to share this thing i know

Expand full comment
author

Interesting, this sounds similar to the "design doc" template. I'd like to learn more though, what are the main differences?

Expand full comment

The key difference i see - ADRs focus more on decision-making process, justification, conclusion and then design doc will talk more about technicalities and specifications of that implementation.

ADRs are mostly done in big companies i think cuz they have wide amount of audience and stakeholders that needs to be aligned with a certain decision.

Expand full comment
author

I see that makes sense. It's like a lightweight "changelog" doc. Thanks for sharing, I'll consider adding something to improve the list. Thanks for sharing!

Expand full comment

This is really great, thank you

Expand full comment
Nov 1, 2023Liked by Ryan Peterman

I signed up just to be able to say thank you for these!

Expand full comment
author

You're welcome, I'm glad they are helpful!

Expand full comment

Love those templates. I'd recommend them even to non-engineers.

My only take here is about the postmortem template. I always add a "Lesson Learned" section. I know those lessons are being inferred from the rest of the text. On the other hand, one of the most important reasons to have a postmortem is the learning opportunity.

In this section I try to dig deeper and find hidden problems in tooling, processes or anything else.

Expand full comment

Great templates! If you are an engineer, I would definitely recommend taking a look at them and adapt them to your needs.

Expand full comment

Thank you, Ryan, for providing these great templates. Besides reusing them in my work in the future, I can learn more about how you tackle a problem through these documents.

Expand full comment

This is what I call being an engineer and not just someone who codes. As engineers we solve problems, we optimize solutions.

It's not only about optimizing the code. Processes like these are repetitive and we can have huge time savings by standardizing, templating and creating SOPs around them.

Thanks for sharing your templates, Ryan! The direction doc is one that I didn't have as a template and it would save me time and structure my thinking

Expand full comment
author

Happy to share, glad the direction doc is new. Hope it’s useful!

Expand full comment

Loved this!

I like how simple you kept the design doc aka RFCs, some be mega bloated.

I've always found it best to keep simple and not make it bloated and annoying haha

Expand full comment
author

Agreed, simple is better when possible. If it gets too bloated then it gets harder for others to read

Expand full comment

This is helpful Ryan. What I would add to this list is a template for taking notes in a meeting. I always try to write those up even just for myself. If I am the organiser, I use the same structure for formal MoMs that I will post to everybody. I mostly write this on a blank OneNote page with the Meeting Details inserted - I just throw in a couple of common Headings that I make sure to fill during the meeting, like Input(Description), Scope, Not in Scope, Deadline, Questions. People often give tasks without explicitly saying the deadline. This always ends in a misinterpretation by someone, so I make sure to ask about the deadline. I use the Questions part to write down my own questions which arise during the meeting, and then the answers when I get them. So it is not an actual file template because OneNote does not have such a feature, but its a short list which is worth much.

Expand full comment
author

Yeah meetings are difficult to template since discussions are often freeform. I often take notes within the meeting agenda which form a kind of outline which I later transfer into formatted writing for others

A template for common meeting agenda structures might be helpful though I agree

Expand full comment

Right, now that I think about it, most of my meetings since I became a SWE were calls where I got told what my new task is, so the form kinda repeats. But in my previous career (construction industry) agenda was super important for this.

Expand full comment

Some useful templates here, Ryan.

Expand full comment

It is very useful for a developer to use these templates. It helps deliver better quality work and better organise the work overall

Expand full comment
Oct 27, 2023Liked by Ryan Peterman

This is just brilliant. Thank you!

Expand full comment