Technical Writing & Communication Resources
💥 Crash Course Starter Pack #
If you’re new to the job, here are essential concepts to get up and running:
- About to work in product development? Types of documentation in product development
- Need to organize the documentation library? A systematic framework for technical documentation authoring
- Are the screenshots hard to maintain? Simplified User Interface
- How to manage stakeholder expectations? RACI Matrix
- How to write better, with clarity? Strunk and White The Elements of Style
🏟️ Organizations #
|Society for Technical Communication
|Tech Comm NZ
|Write The Docs
|Software bias, but any profession
|American Medical Writers Association
|For medical, obviously
📑 Style Guides #
|ASD Simplified Technical English
|Great for hardware and international reach. 1 word = 1 meaning!
|Microsoft Writing Style Guide
|If you write about computer technology, this guide is for you.
|Google Developer Style Guide
|Editorial guidelines for writing Google-related developer documentation.
|Writing for an inclusive web audience
|Strunk and White The Elements of Style
|It aims to give in brief space the principal requirements of plain English style.
▶️ Videos #
|How to be a window for your audience.
🌐 Sites #
|Tech writer portfolio for job applications.
|Why you should separate documentation into 4 types of deliverables.
|Programming for academics, archivists and writers.
|Anything from business correspondence to design documents.
|I’d Rather Be Writing
|Tom Johnson’s blog; he writes and hosts interviews and podcasts.
|Blog of a software-based technical writer.
🔄 Related Fields #
Stuff that pertains to other industries and specialties.
ℹ️ Information Architecture #
|Types of software documentation
|Article which explains the differences between product and process docs.
|MECE Framework McKinsey
|The Mutually Exclusive and Collectively Exhaustive (MECE) principle is used to break data into manageable and efficient parts. This page has nice diagrams to explain it.
|Nielsen Norman Group UX Research
|A group that publishes some of its UX findings for free.
🎙️ Journalism #
|Help a Reporter
|Tinder for journalists.
⚖️ Intellectual Property #
IP is actually kinda funny, you gotta write clearly, but without giving away too much detail. Some spoofing is in order…
|WIPO Patent Drafting Manual
|Upmath Online Editor
|Generate high quality equations from LaTeX.
🖥 DevRel #
The difference between a software developer and an engineer is that engineers document their stuff. Opinionated Developer Relations article.
|API Learning Process
|Research paper on how developers get acquainted with a new API.
|Docs Like Code
|Introduction to the concept.
API Docs I like:
No better teacher than good examples. Copy and steal from the Old Masters.
- Structure is direct and straightforward.
- Not too many animations.
- Tables are clean (unlike some monstrocities that span the horizontal width and have 3+ columns for some reason).
- No collapsing menus in the body content.
- They hide the scrollbar and it’s 1 gigantic page (easy to Ctrl-F).
🛸 Professional Software #
This list contains software for business use, compared to the open-source/personal stuff listed on the Writing Tools page. Each piece of software has a special niche, and you don’t have to use everything, however it’s good to know the special advantages of a software.
Plain Text Editors #
A simple text editor is important for those times when you really just need to jot something down, and you don’t need fancy styles.
|Simplistic, quick, human-readable plain text.
|Plain-text for authoring technical layouts.
|rST for Sphinx and Python-based docs.
🎩 Help Authoring Tools (HAT) #
In general, HATs are the flagship tools of the trade, specifically designed to organize technical manuals and reusable segments. This style of composition is called topic-based authoring, and alternatively the tool may be known as a CCMS. They allow setting variables for output targets, “programming” which tailors a written product to many audiences and consumption channels.
|A long-standing contender.
|Same as above.
|Software documentation kit.
|Previously known as easyDITA.
|Cloud-based CCMS application.
|Help and Manual
💡 Knowledgebase #
While HATs can be used to create a knowledgebase (KB). KB style is suited for customer support, which assumes a less expert audience, and typically hosts more multimedia outputs (videos, interaction, diagrams, learning material) besides the usual PDF or article.
Wikis are another… strange hybrid. It’s like a knowledgebase or cloud storage, but usually private, and sometimes you want to share with guests. They elicit a “yikes” from me. Kind of a necessary evil.
|JIRA integrated wiki and notes repository. Free if under 10 users.
|Integrated with OneDrive and hosts wiki/intranet portals.
|A note-taking and sharing system. Has a free tier.
|Similar to Notion.
|Cheatsheet style cards, works well with Slack chat.
📰 Design and Publish #
Crossover into graphic design and communication with visual mediums.
|Pre-made templates for print and social media.
|Flexible and used for all kinds of graphics.
|It’s not as good as Photoshop for things like mockups, but it’s free.
|The current industry standard for print. Excellent control over typography and layout.
|It’s almost as good as InDesign for the unbeatable price of
|MS Office Publisher
|Casual tool if you’re not a full-blown graphic designer.
|An excellent program for creating clean illustrations for print or web, and even animations.
|A free program with a similar niche to Illustrator, but has poorer CMYK (print ink color) support. It’s better for creating SVG.
|Shining paragon of UI/UX composition, but Mac-only requirement is limiting.
|Has advanced interaction capabilities for high-fidelity demos.
|A free collaboration platform offered by Google.
|Similar to the above.
|Wireframe designer, low-fidelty and UX focused over UI.
📌 Business Process #
The stuff that you need to make your point (slide decks, demos).
|Flowchart maker. Usually paid for by your company.
|diagrams.net / draw.io
|Free and open-source chart maker.
A lot of people use MS Office PowerPoint / Google Slides to create flowcharts, since they have templates and can insert shapes, but they’re not as good as dedicated diagramming programs.
|If you’re a paralegal, you probably need something like this.
|Product development management used in a lot of enterprises.
|A lighter version of JIRA.
|Similar to Trello.
If you’re entrenched in the Microsoft Windows ecosystem and use Outlook for email…
📽 Multimedia #
Typically Zoom, WebEx and conference software have an inbuilt recording feature, but for extra polish you may need additional programs.
|Screenshot tool that lets you add arrows, blurs and callouts.
|Open-source version of Snagit.
|Free, quick GIF screen capture utility
|Open-source, for recording and streaming.
|Beginner-friendly screen capture program.
|Open-source, free video editor.
|An up-and-coming video editor aimed at the professional market. Still in beta but usable.
|Professional-grade video editor made by Blackmagic Design with a free and pro version.
🤖 Automation #
If your department writes tests for UIs, get tech writers to become a stakeholder for test results, reports and screenshots.
- Cypress Frontend Testing | Example of a software developer’s UI testing suite.
|Developer Portal integrated docs.
|Multi-repo aggregation documentation.
|Pull Docs From Multi Repos
|My own implementation available as a Powershell script.
OpenAPI Generators #
|Generate beautiful doc pages from OpenAPI spec; a modern successor to SwaggerUI.