Writing Guidelines for Engineering Projects

The difference between a good design doc and a great one is usually clarity. Technical writing should be crisp and to the point. So, it is always better to treat every sentence like it has a cost. After writing, cut aggressively. Remove extra words. Then check if a line can go. Sometimes even a full paragraph is unnecessary. One thing I always do is to start the doc with the conclusion; this way, the reader/reviewer knows where we are heading. This is contrary to how most engineers write docs - listing every approach first and only concluding at the end. That slows readers down. I avoid this because long explanations make people lose track; most readers want the conclusion quickly. So, always start with the answer and why it matters. Then add details and alternatives below for those who want depth. A habit that helps is a quick editing pass like this: - Remove filler words and repeated ideas. - Break long sentences into smaller ones. - Prefer bullets when listing options or steps. - Check if the first section clearly states the outcome. - Add a link or short explanation where a reader may pause. Empathy matters more than most people realize. Try to read your document as someone new to the topic. Ask yourself what might confuse them. Add the missing context. Add the helpful link. Let the ideas evolve naturally from problem to solution. This skill develops over time. Use simple language and fewer buzzwords. The goal is to communicate, not impress. Simple documents get read more. More readers means better alignment and better visibility for the work. Finally, always provide enough context. A short setup about the problem, constraints, and prior decisions goes a long way. It helps readers understand why the decision exists, and, of course, it prevents unnecessary back and forth later. Hope this helps.

In my 14yrs career in engineering working for Big Tech companies such as Google and Uber, there is no other skill I used more than writing. And no, I don’t mean writing code. I mean English writing. Emails, Design Docs, Presentations, Feedback, Code Reviews, you name it. Here's how I make my written communication clear, effective, and punchy. 👇 Written communication can sometimes be daunting, especially for non-native speakers—like me. That’s why I wanted to share  the 6 questions that I use when writing anything. This helps me communicate more effectively and connect with my audience better. 1. Who is my target audience? Identify the specific group or individuals you are speaking to. Knowing your audience assists you in customizing your writing to meet their requirements and interests. 2. What is my main objective or purpose? Clarify the primary goal of your writing. Whether it's to inform, persuade, entertain, or educate, knowing your objective guides your content. 3. What key points do I want to convey? Identify the main idea or key points you want to communicate. This will help you stay focused and make sure your message is clear and logical. 4. Why should the reader care about this? Consider the value or benefit your writing offers to the reader. Highlight how it addresses their needs or solves a problem. 5. Is my writing clear, concise, and organized? Make sure your content is clear and easy to understand. Keep the flow logical and avoid using complex language or jargon that might confuse the reader. 6. Can I make my writing shorter? The answer is always yes. So make sure to edit edit edit. Brevity saves time for both the writer and the reader. What else would you add to this list? How does your writing process look like? ♻️ Please repost if you found this useful

Many requirements start with good intentions, yet end up looking like “The system should work fast and be user-friendly.” The real shift begins earlier than wording. A good requirement starts with a clear understanding of the user problem, not with a solution idea. Before writing anything, clarify three simple questions: Who needs this. What they need. Why it matters. A common and effective pattern to structure this thinking is the user story: “As a [role], I want [what] so that [value].” This format keeps the focus on real stakeholders and expected outcomes, rather than on technical preferences. From there, a requirement becomes a statement that translates or expresses a need and its associated constraints and conditions. A well formed specified requirement: ✓ Addresses a problem or objective. ✓ Is qualified by measurable conditions. ✓ Is bounded by constraints. ✓ Defines system performance or capability. ✓ Can be verified. It shall state what the system must do, not how it is designed or implemented. To support verification, each requirement should be necessary, unambiguous, complete, singular, feasible, verifiable, and correct. Clear wording is often the simplest improvement. Reserve: → “Shall” for mandatory, binding requirements. → “Shall not” for prohibitions. → “Should” for desirable but non mandatory goals. → “May” for optional provisions. → “Will” for statements of fact or future context. × It is best to avoid using the term ‘must’. Avoid vague or untestable language such as “user friendly”, “easy”, “fast”, “if possible”, “as appropriate”, “best”, “minimal”, and ambiguous pronouns without a clear subject. Strong requirements are short, written in active voice, with a clear subject, verb, and object, and measurable terms instead of subjective adjectives. A practical framework to structure a requirement is: [CONDITION] + [SUBJECT] + [ACTION] + [OBJECT] + [CONSTRAINT OF ACTION] You will find more example in the cheat sheet ↆ What are the small writing rules or frameworks that really make a difference in daily projects, and would you mind sharing the ones that work best for you?

The BRD serves as a formal agreement between the organization and stakeholders on what a project will deliver. Here’s a breakdown of how to write a BRD, step by step: ✅ Project Overview Purpose: Start by clearly defining the purpose of the project. Explain what the project aims to achieve and why it is necessary. Background: Provide context by discussing any events or circumstances that have led to the need for this project. ✅ Scope In-Scope: Define what is included in the project, detailing the services, processes, or systems that will be affected. Out-of-Scope: Equally important is to mention what is excluded from the project. This helps prevent scope creep and sets clear boundaries. ✅ Objectives and Goals Clearly articulate the business objectives the project seeks to meet. Objectives should be Specific, Measurable, Achievable, Relevant, and Time-bound (SMART). ✅ Stakeholder Analysis Identify all the stakeholders involved in the project, including end-users, project sponsors, and external parties. Understand their interests and how the project impacts them. ✅ Requirements 👉 Business Requirements: Describe the high-level business policies and rules, business process changes, data requirements, and any high-level requirements that are necessary for achieving the business objectives. 👉 Functional Requirements: Detail the functionality that the software or system must have in order to meet the business requirements. This includes workflows, system functionalities, and user interactions. 👉 Non-Functional Requirements: Specify the attributes the system must have, such as performance, usability, reliability, and security. ✅ Constraints and Assumptions 👉 Constraints: List any restrictions or limitations (budgetary, system, technical) that must be considered when developing the solution. 👉 Assumptions: Document any assumptions that are made during the requirement gathering phase. ✅ Business Process Descriptions Include current ("as-is") and proposed ("to-be") business processes. Diagrams and flowcharts can be very effective here for illustrating how current processes will change. ✅ Detailed Requirements 👉 User Stories or Use Cases: These provide detailed descriptions of how users will interact with the system. Each use case should outline the steps from the user's start point to the end goal. 👉 Data Requirements: Define the data that needs to be inputted, stored, and outputted by the system. This section may also include data migration plans. ✅ Acceptance Criteria Define what criteria must be met for the project deliverables to be accepted by the stakeholders. ✅ Project Timeline Provide an estimated timeline for the project’s milestones and deliverables. ✅ Approval Specify the individuals who have the authority to approve the BRD. 𝐓𝐢𝐩:-A BRD is not a one-and-done document. It should be reviewed regularly throughout the project to ensure it continues to meet the evolving project needs. BA Helpline

In the past 10 years, I’ve reviewed 100s of design docs. Here’s how to write review-ready design docs in 3 simple steps. 1/ Start with a skeleton, write these: • Metadata (Title, authors, status, date, reviewers, approvers) • Context and background • Problem statement • Summary or tl;dr (Optional) • Proposed solution details with tradeoffs and selection rationale  • Other alternatives considered • Failure modes of the proposed solution • Open Questions • References (Optional) 2/ After the skeleton, fill in the content under these headings. -If there are sub-sections, add sub-headings.  -Provide examples and sample calculations. -Use bullet points and lists wherever applicable -Include architectural diagrams, graphs and tables. 3/ If the document is large, put a summary after the problem statement. Start with the skeleton, take it one step at a time, and before you know it, you are done! Remember, a good design doc: -helps understand design decisions and implementation details -helps in identifying potential issues and challenges early  -gives a clear understanding of the architecture -serves as a reference doc during the project While you write and review, make sure your work follows these guidelines. I know writing detailed docs doesn’t come naturally when you’re focused on problem solving. But it’s an essential skill you have to learn to level up. just follow a simple procedure, practice and you’ll get the hang of it. – P.S: Check out additional writing tips in the comments below ↓