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 #
| Name | Note |
|---|---|
| Tekom | EU |
| 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 #
| Name | Note |
|---|---|
| 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 #
| Title | Note |
|---|---|
| Mastering Style | How to be a window for your audience. |
🌐 Sites #
| Title | Note |
|---|---|
| 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 #
| Title | Note |
|---|---|
| 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 #
| Title | Note |
|---|---|
| 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…
| Title | Note |
|---|---|
| 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.
| Title | Note |
|---|---|
| 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.
| Conventions | |
|---|---|
| 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.
| HAT | |
|---|---|
| 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. |
| Calenco | entreprise français |
| Author-it | |
| 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.
| KB | |
|---|---|
| Adobe Robohelp | I’m getting sick of typing “Adobe”. |
| Document360 | Markdown-based authoring. |
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.
| Wiki | |
|---|---|
| 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.
| General | |
|---|---|
| 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. |
| Physical | |
|---|---|
| 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 free. |
| MS Office Publisher | Casual tool if you’re not a full-blown graphic designer. |
| Digital | |
|---|---|
| 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. |
| UI/UX | |
|---|---|
| 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).
| Diagrams | |
|---|---|
| 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.
| Management | |
|---|---|
| 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. |
Outlook #
If you’re entrenched in the Microsoft Windows ecosystem and use Outlook for email…
The Desktop Sticky Notes app syncs with the Notes section of your Outlook client. It’s pretty handy.
📽 Multimedia #
Typically Zoom, WebEx and conference software have an inbuilt recording feature, but for extra polish you may need additional programs.
| Images | |
|---|---|
| Snagit | Screenshot tool that lets you add arrows, blurs and callouts. |
| Greenshot | Open-source version of Snagit. |
| LICEcap | Free, quick GIF screen capture utility |
| Video Recording | |
|---|---|
| OBS Studio | Open-source, for recording and streaming. |
| Camtasia | Beginner-friendly screen capture program. |
| Post-processing | |
|---|---|
| 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. |
| Script | |
|---|---|
| KIT Scenarist | Open-source script writing program. |
| Celtx | Screenplay creation suite. |
🤖 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.
| Docs-as-code | |
|---|---|
| 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 #
| Title | Note |
|---|---|
| Rapidoc | Generate beautiful doc pages from OpenAPI spec; a modern successor to SwaggerUI. |