3 Tips To Have Your Engineers Read Your Document

When I started out as a Product Manager, there was one conversation that annoyed me more than anything else:

Dev: I need your help.

Me: Sure, what's up?

Dev: Can you explain this spec to me?

Me: Sure, what part?

Dev: All of it.

Me: What?!

‍

I would spend hours crafting a comprehensive spec document. However, no one would read it. The developers would come directly to me asking to explain the entire spec verbally.

It was incredibly frustrating.

"Why can't people just read what I've written?", I used to wonder.

But then I went into introspection.

I asked myself: would I want to read this 34-page document that read like Shakespeare on a Sunday morning?

‍

So, I probed around & discovered a few problems:

• My spec was too verbose & engineers were intimidated by it. They were afraid they'd miss a point & be blamed for it
• The way I organized the spec was convoluted & didn't align with the engineer's cognition model
• At times, the engineer's English fluency was an impediment
• The developer was unsure where to start & how to deconstruct the spec

It made me realize that the tech team was my user here. My product management instincts kicked in & reminded me that the customer doesn't care about the effort you put in. They only care about what your output can do for them.

So, that made me wonder.

‍

In what scenarios are people motivated enough to read & follow a document?

• I noticed how my mother would diligently prepare foreign recipes in the kitchen by playing/pausing Youtube videos. The format was a perfect blend of visual and instructional narration
• Similarly, my 10 year old kid had no problems assembling an ambitious Lego set meant for 14 year-olds as long as he followed the illustrated manual
• Whenever I had to build a piece of furniture from IKEA, the manual was my only go-to. I never had to call in anyone else

‍

Gradually, I found a balance:

• I adapted my spec to start with the business case & a high-level user story list
• I used to provide a wireframe / prototype but it was delivered separately as a link. So, instead, I embedded annotated screens from the wireframe on every page of the spec (much like a visual manual)
• I started conducting a kick-off meeting for each sprint narrating over the wireframes & spec in detail. By the end of the intense Q&A that followed, a lot of the confusions would be addressed

‍

In fact, here's an exercise you can do to understand how your engineers like to consume information:

1. Pick a user story from the existing product. (something the team knows well.)
2. Ask your engineers to describe the user story verbally & then also write it down in a couple of pages
3. Their responses will give you a window into their mental model & give you hints on how you should structure your spec. Ex: Do they prefer checklists? Do they start from the data model? Do they like to read psuedo-code or flowcharts?