Edition 11 - 3 Documents That Could Save Your Next Project

Picture this , it's been 6 months since you released a complex feature that’s been well received. It now needs enhancements based on user feedback. It’s got a ton of nuances, and no one seems to be able to remember all the different flows supported from the get-go. You rope in the QA team, they’ve got a set of test cases, and you’re building against that now.
Do you see this working out, ?

The message of why we’re creating documentation has been lost over time. We often create documentation that helps us instead of focusing on helping the reader. As a result, documents meant to provide clarity end up looking cluttered and confusing. They present varied perspectives in a single document, with charts and graphs that seem out of place and a mash-up of information on every topic the author knows. It just fails to deliver the clear, concise content the reader needs.

The moment we start providing information in a context and format that people understand, we make it easier for them to ask the right questions and improve their work.

This prevents assumptions and ensures that everyone is on the same page. Assumptions are the top cause of rework, and ambiguity often leads to regressions. Good documentation helps solve both problems—it provides clarity, eliminates ambiguity, and aligns everyone's expectations.

Before moving ahead, I’m very excited to share that this edition is sponsored by 1440.

The Daily Newsletter for Intellectually Curious Readers

• We scour 100+ sources daily

• Read by CEOs, scientists, business owners and more

• 3.5 million subscribers

Sign up today!

When creating documentation, or rather, any kind of written content, the goal is to have a clear understanding of who your reader is. The niche-r, the better. Think about the persona, their journey to discover your content, and what action you’d like them to perform after reading. Tailoring content to a specific audience makes it easier for them to consume it. And, in this edition of LeadReads, I’ll show you my framework and one that is used across Wednesday when creating documentation.

Step 1: Before you even begin writing documentation, fill out this simple questionnaire.

1. Audience

2. Assumptions

3. Why should they read this?

4. Side Effects

4 simple questions. Here is a filled-up version of the questionnaire for this tutorial on integration tests in Node.js.

Filling the questionnaire helps understand why someone is reading this, where they are in terms of their level of understanding of the content, and what you would like to convey to them.

Now leverage what Wednesday’s learned and get your copy of the Wednesday approved:

• Business Requirement Document

• Product Requirement Document

• Technical Requirement Document

Follow these simple rules while using it:

• Create these 3 artefacts only for something that will take more than 3 months, but not more than 6 months.

• If you’re spending more than 20% of the total allocated time on documentation, you’re doing it wrong. If you’ve got 10 days to do something, spend 2 days in documentation. More than that and you’re procrastinating

• Do not parallelise this process; do not make assumptions. Do it sequentially. Ask questions.

• This entire exercise is being done to ensure alignment and a 360-degree outlook. If you’re not able to carve an actionable for each header, you’re doing it wrong.

• If you’ve got repetition across the different documents, then you’re doing it wrong. The goal is to make sure that there is alignment across the different departments, not merely fill these documents. Each of header in each document addresses a specific pain-point. If you feel it’s repetitive, reach out, and I’ll help.

• Who writes it?

  • BRD → written by the CEO or Project Sponsor. You need to focus on the business outcomes and success indicators here. If you’re talking about the product here, you’re doing it wrong. If you’ve got a solid business idea, then an app/website/Excel is just a means to an end. Focus on the business opportunity here.

  • PRD → written by the Product Manager. You need to focus on how you will acquire users, what will keep them engaged, and what value your product is providing. It will contain important artefacts like the User Flow Diagram, the User Persona and Journey that support and drive important product decisions.

  • TRD → written by the Solutions Architect or Tech Lead. Given the business opportunity and the product requirements, you need to figure out the best technical approach to achieve the desired result. It will contain important artefacts like C4 Diagrams, Sequence Diagrams, and Testing Strategies, among others, that will govern and drive important technical decisions.

As promised, the secret sauce for success. Download our templates and start implementing these changes today to see the difference

• BRD

• PRD

• TRD

Feel free to duplicate and use.

DATA TALES

Google emphasises the importance of clear and concise documentation in its engineering culture. They advocate for documentation to be written for the reader, not the writer, ensuring that it is accessible and useful. This approach helps prevent misunderstandings and reduces rework.

WHAT I’M READING

I'm currently reading "Hope Is Not a Strategy: The 6 Keys to Winning the Complex Sale" by Rick Page, a compelling guide on mastering the art of selling complex, high-tech products and services. The book offers practical insights into navigating sophisticated sales processes, emphasizing strategic approaches over mere optimism.

HAPPENINGS AT WEDNESDAY

• Want to get a sneak peek into what the life of a senior software engineer at Wednesday looks like? Watch it here.

• We welcomed 3 new Asgardians to our Wednesday family.

EARN REWARDS⚡️

You can get rewards for referring your network to LeadReads 👇️ 

1 referral - LinkedIn Shoutout from Wednesday
3 referrals - Our Data Engineering Onboarding Kit
5 referrals - Our Service Picker Tool (A must-have for developers)

You currently have 0 referrals, only 1 away from receiving a LinkedIn Shoutout.

Or send this link to your friends: https://lead-reads.beehiiv.com/subscribe?ref=PLACEHOLDER

Hi, I’m Mohammed Ali Chherawalla (Mac), Co-founder & CTO at Wednesday Solutions, a specialized engineering services company with a focus on Applied AI, Data, and Application Modernization. I make it a point to read every message from my subscribers, so don't hesitate to share your thoughts with me.