Writing Guidelines for Engineering Projects

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

“We’re bleeding clients left and right,” a decision-maker at a global engineering firm told me after hiring us to help. << The Problem >> New hires were producing work that: — Included irrelevant information  — Failed to meet readers' needs And although the senior engineers designated as reviewers were capable of writing clear documentation, they didn’t know how to guide new hires to do the same. << The Deadly Assumption >> So hiring top engineering grads wasn’t their problem. The problem was *assuming* that the engineers’ writing skills were just as good as their engineering skills. But even elite institutions such as MIT, CalTech, and Stanford don’t necessarily invest a lot in the kind of writing courses that help engineers produce clear documents. Instead, they learn to write pull-your-hair-while-screaming-profanities obtuse documents in esoteric academese. Sidebar: this is a common problem I see when working with engineering (and, in fact, most tech) firms. Namely, that the ability to write well usually doesn’t translate into the ability to *teach* how to write well. << Down the Rabbit Hole >> Our audit revealed that new hires had a *single* example of what a high-quality document should look like. No multiple examples. No style guide. No consensus on reviewing. No training. Poor templates. To make matters worse, reviewers would despair and, instead of providing feedback, push confusing documents on to clients. Who, in turn, would come back and express their frustration. Yikes. << The Solution >> After applying a liberal amount of elbow grease, we: — Created standards to train new writers  — Designed mentorship programs and guidance documents — Developed and taught a series of customized writing workshops focused on writing for modern readers << The Outcome >> Three months after implementing our program, the company reported: ✔ 15% less time spent training new writers on company standards ✔ More experienced engineers mentoring new hires and contributing to guidance documents and templates ✔ Newer engineers even teaching some of the more experienced staff strategies from our workshops Overall, new engineers were onboarded 2 weeks sooner and required less oversight from their superiors. And clients stopped making irate phone calls. Nice. << The Takeaway >> Your engineers might have some of the most sophisticated wetware on the planet, but that DOES NOT mean they don't need writing training. The good news is that if you have the right kind of training, mentorship, and standardization of documents in place, they’re also the kind of people who learn FAST.

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 ↓