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||USA|
|Tech Comm NZ||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.|
|Mailchimp Principles||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 #
|Mastering Style||How to be a window for your audience.|
🌐 Sites #
|Portfolio Ideas||Tech writer portfolio for job applications.|
|Diátaxis Framework||Why you should separate documentation into 4 types of deliverables.|
|Programming Historian||Programming for academics, archivists and writers.|
|Sample Templates||Anything from business correspondence to design documents.|
|I’d Rather Be Writing||Tom Johnson’s blog; he writes and hosts interviews and podcasts.|
|Kayce Basques||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||International standard|
|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.
|Markdown||Simplistic, quick, human-readable plain text.|
|Asciidoctor||Plain-text for authoring technical layouts.|
|reStructured Text||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.
|Madcap Flare||A long-standing contender.|
|Adobe Framemaker||Same as above.|
|Doxygen||Software documentation kit.|
|Heretto||Previously known as easyDITA.|
|Paligo||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.
|Confluence||JIRA integrated wiki and notes repository. Free if under 10 users.|
|SharePoint||Integrated with OneDrive and hosts wiki/intranet portals.|
|Notion||A note-taking and sharing system. Has a free tier.|
|Nuclino||Similar to Notion.|
|Guru||Cheatsheet style cards, works well with Slack chat.|
📰 Design and Publish #
Crossover into graphic design and communication with visual mediums.
|Canva||Pre-made templates for print and social media.|
|Adobe Photoshop||Flexible and used for all kinds of graphics.|
|GIMP||It’s not as good as Photoshop for things like mockups, but it’s free.|
|Adobe InDesign||The current industry standard for print. Excellent control over typography and layout.|
|Scribus||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.|
|Adobe Illustrator||An excellent program for creating clean illustrations for print or web, and even animations.|
|Inkscape||A free program with a similar niche to Illustrator, but has poorer CMYK (print ink color) support. It’s better for creating SVG.|
|Sketch||Shining paragon of UI/UX composition, but Mac-only requirement is limiting.|
|Axure||Has advanced interaction capabilities for high-fidelity demos.|
|Figma||A free collaboration platform offered by Google.|
|Adobe XD||Similar to the above.|
|Balsamiq||Wireframe designer, low-fidelty and UX focused over UI.|
📌 Business Process #
The stuff that you need to make your point (slide decks, demos).
|Microsoft Visio||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.
|Aeon Timeline||If you’re a paralegal, you probably need something like this.|
|JIRA||Product development management used in a lot of enterprises.|
|Trello||A lighter version of JIRA.|
|Asana||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.
|Snagit||Screenshot tool that lets you add arrows, blurs and callouts.|
|Greenshot||Open-source version of Snagit.|
|LICEcap||Free, quick GIF screen capture utility|
|OBS Studio||Open-source, for recording and streaming.|
|Camtasia||Beginner-friendly screen capture program.|
|Kdenlive||Open-source, free video editor.|
|Olive||An up-and-coming video editor aimed at the professional market. Still in beta but usable.|
|Davinci Resolve||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.
|Backstage Techdocs||Developer Portal integrated docs.|
|Antora||Multi-repo aggregation documentation.|
|Pull Docs From Multi Repos||My own implementation available as a Powershell script.|
OpenAPI Generators #
|Rapidoc||Generate beautiful doc pages from OpenAPI spec; a modern successor to SwaggerUI.|