Writing Technical Documents Well
Effective technical writing requires clarity, simplicity, and audience awareness. Key strategies include structured storytelling, active voice, and avoiding jargon, ensuring documents remain relevant and impactful over time.
Read original article
Writing a technical document can be challenging due to the need for clarity and precision. The author emphasizes the importance of understanding the audience and tailoring the content accordingly. Key strategies include writing simply, avoiding jargon, and removing unnecessary words. The document should be structured to tell a clear story, often using the SCR (Situation, Complication, Resolution) format. The author advises applying the "So what?" test to ensure that every statement adds value and quantifies impact. Additionally, using active voice enhances clarity and confidence in the writing. The author also highlights the importance of creating non-obsolete documents by avoiding time-sensitive references and providing context about the document's authorship and approval. Overall, these tips aim to help writers avoid common pitfalls and improve the effectiveness of their technical writing.
- Writing for the audience is crucial for effective communication.
- Simplicity and clarity should be prioritized in technical documents.
- A structured approach helps convey information more effectively.
- Active voice is preferred for concise and clear writing.
- Avoiding time-sensitive references ensures the longevity of documents.
Related
Git Workflows for API Technical Writers
Technical writers encounter challenges in maintaining API documentation aligned with evolving designs. Git workflows provide version control and collaboration benefits. Strategies like merging copy improvements, code annotations, and OpenAPI overlays enhance documentation quality. Involving writers in API design ensures user-centric content. Storing docs in separate repositories can resolve Git conflicts.
How to Shorten Scientific Manuscripts
Guidance on shortening scientific manuscripts efficiently: adopt a concise mindset, prune unnecessary info, avoid repetition, aim for clear messages, delete empty words, and reduce emotional burden. Emphasizes clear, concise writing to engage readers effectively amid decreasing article lengths in scientific publications.
The Documentation Tradeoff
Kent Beck's article discusses the complexities of software documentation, emphasizing effective communication over excessive documentation. He critiques "self-documenting code" and the neo-waterfall approach, advocating for alternatives like discussions and tests.
Not Another Technical Debt Article
The article critiques technical debt discussions, arguing they often lack practical solutions. It advocates for direct action to fix technical debt, emphasizing collaboration and social dynamics among engineers for effective resolution.
How we communicate signals seniority
Effective communication influences perceptions of leadership. Emphasizing outcomes over processes and aligning projects with measurable business impacts is essential for career advancement, particularly for product leaders.
18 commentsIt's been a few years since I've returned to it, but the material in Zinsser's book has been useful to me as an engineer that has to occasionally write for both fellow engineers and non-technical folks. I would recommend Zinsser's book if you like the content in the article and wouldn't mind a bit more.
E.g. "The foo program is running on the bar server. Who is in charge of that?" vs "The foo program is running on the bar server. Who is in charge of the bar server?"
Unfortunately I can't find it anymore -- if someone knows which post I mean, I'd appreciate sharing it with me again.
https://www.americanscientist.org/blog/the-long-view/the-sci...
Invest in improving your writing skills. It will pay dividends in every aspect of your business.
For prose, replace all common adjectives by more specific or descriptive one, or even remove them too and describe properties. For example: The F-35 passed by my house. When I heard its sound, the jet had already disappeared at the horizon. (This describes super-sonic speed without an adjective or an overly precise speed number.)
Edit: past perfect based on comment
Frontloading information is my favorite, where instead of building to the core conclusion you start with it and then expand.
https://www.goodreads.com/book/show/28448362-writing-without...
Related
Git Workflows for API Technical Writers
Technical writers encounter challenges in maintaining API documentation aligned with evolving designs. Git workflows provide version control and collaboration benefits. Strategies like merging copy improvements, code annotations, and OpenAPI overlays enhance documentation quality. Involving writers in API design ensures user-centric content. Storing docs in separate repositories can resolve Git conflicts.
How to Shorten Scientific Manuscripts
Guidance on shortening scientific manuscripts efficiently: adopt a concise mindset, prune unnecessary info, avoid repetition, aim for clear messages, delete empty words, and reduce emotional burden. Emphasizes clear, concise writing to engage readers effectively amid decreasing article lengths in scientific publications.
The Documentation Tradeoff
Kent Beck's article discusses the complexities of software documentation, emphasizing effective communication over excessive documentation. He critiques "self-documenting code" and the neo-waterfall approach, advocating for alternatives like discussions and tests.
Not Another Technical Debt Article
The article critiques technical debt discussions, arguing they often lack practical solutions. It advocates for direct action to fix technical debt, emphasizing collaboration and social dynamics among engineers for effective resolution.
How we communicate signals seniority
Effective communication influences perceptions of leadership. Emphasizing outcomes over processes and aligning projects with measurable business impacts is essential for career advancement, particularly for product leaders.