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

📌 How to write a professional structural calculation report Structural engineers who produce accurate calculations but provide poorly written calculation reports can create a negative impression on reviewers. The report should be clear and informative not only to facilitate a smooth review process but also for the benefit of the contractors involved. For instance, the structural steel contractor often relies on this report to design the connections and verify the members. Therefore, structural engineers need to possess strong reporting skills. 💡 Keep in mind the following points that should be avoided in the calculation report: 1. Avoid Using Screenshots: Do not create a photo album by inserting screenshots from software. The purpose of the report is not to explain the analysis process or teach the reviewer about the software. Only include essential screenshots if necessary. 2. Provide Complete Information: Do not include anonymous or incomplete information that could mislead the reader. 3. Ensure Clarity: Avoid unclear procedures that might confuse the reviewer regarding the design theory used. The report should be straightforward and to the point. 4. Balance Precision and Comprehension: Aim for a balance between providing precise information and avoiding a learning manual. Assume that the reader is familiar and experienced, and they require only clear and accurate information. 💡 Contents of a professional design calculation report : 1. Cover Page: - Title - Project reference - Client - Company or author(s) - Date of submission 2. Detailed Table of Contents 3. Revision Table and Approvals - Signature of the design engineer(s) - Approvals from relevant authorities or stakeholders 4. Executive Summary - Brief overview of the design project - Key objectives - Summary of findings and outcomes - Highlights of critical calculations or results 5. Introduction - Scope and purpose of the report - Background of the project 6. Design Objectives - Specific goals for the design - Functional, structural, environmental, or performance-based objectives 7. References List of all references used, including standards and codes, textbooks or journals, and software manuals. 8. Input Data and Assumptions - Material properties - Environmental conditions - Dimensional data - Assumptions made during calculations - References to applicable codes or standards 9. Methodology - Design criteria and assumptions - Selected design approach - Software or tools - Analytical methods applied 10. Design Calculations - Detailed calculations with references to input values - Load calculations - Structural analysis - Structural design & checks based on analysis results. 11. Results and Analysis: - Summary of calculation results - Discussion of potential risks or design limitations 12. Conclusion - Recap of key outcomes - Statement of the design’s adequacy and reliability 13. Appendices - Tables, drawings or schematics

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 ↓

You are an amazing Engineer... but can you write? I remember studying Technical Writing as one subject in Uni. It was overlooked at the time only later did I realise it’s as important as any technical subject we studied. Because you can be the smartest engineer in the room… but if you can’t write clearly, your work is at risk of being misunderstood, ignored, or misused. Too often, we treat documentation as “boring paperwork.” In reality, it’s one of the strongest forms of risk management we have. Here’s the truth 👇 Most disputes, variations, and project blowouts don’t begin with wrong soil data or poor drainage estimates. They begin with unclear words and missing documentation because decision makers don’t base their decisions on your equations. They act on your written conclusions whether it’s a feasibility study, a concept design report, or a one-page memo. 📑 What are some examples of essential documentations in Engineering? 1- Emails – a well-written email can save hours of meetings. 2- Scope of Work – defines exactly what is included and excluded. 3- Basis of Design – records assumptions, limitations, and methodology. 4- Risk Registers – highlight what could go wrong and how it’s managed. 5- Design Reports & Technical Memos – don’t just show calculations. They justify decisions, explain uncertainties, and provide a defensible trail. 6- RFPs – clear Requests for Proposal avoid vague scope and misunderstandings. 7- Proposals – define exactly what you are (and aren’t) proposing. This protects you from future disputes and scope creep. So how do you strengthen your technical writing skills? ✍️ Read engineering journals and papers to absorb style and clarity. ✍️ When you join a company, read archived reports to familiarise yourself with format, structure, and language. ✍️ Use AI tools to proofread not to write for you, but to ensure your work is grammatically sound and professional. ⚠️ Remember No matter how good your design is, it’s only as good as you document it. Islam Seif - #Engineering #TechnicalWriting