Technical Writing & Communication Resources

💥 Crash Course Starter Pack #

If you’re new to the job, here are essential concepts to get up and running:

  1. About to work in product development? Types of documentation in product development
  2. Need to organize the documentation library? A systematic framework for technical documentation authoring
  3. Are the screenshots hard to maintain? Simplified User Interface
  4. How to manage stakeholder expectations? RACI Matrix
  5. How to write better, with clarity? Strunk and White The Elements of Style

🏟️ Organizations #

NameNote
TekomEU
Society for Technical CommunicationUSA
Tech Comm NZNZ
Write The DocsSoftware bias, but any profession
American Medical Writers AssociationFor medical, obviously

📑 Style Guides #

NameNote
ASD Simplified Technical EnglishGreat for hardware and international reach. 1 word = 1 meaning!
Microsoft Writing Style GuideIf you write about computer technology, this guide is for you.
Google Developer Style GuideEditorial guidelines for writing Google-related developer documentation.
Mailchimp PrinciplesWriting for an inclusive web audience
Strunk and White The Elements of StyleIt aims to give in brief space the principal requirements of plain English style.

▶️ Videos #

TitleNote
Mastering StyleHow to be a window for your audience.

🌐 Sites #

TitleNote
Portfolio IdeasTech writer portfolio for job applications.
Diátaxis FrameworkWhy you should separate documentation into 4 types of deliverables.
Programming HistorianProgramming for academics, archivists and writers.
Sample TemplatesAnything from business correspondence to design documents.
I’d Rather Be WritingTom Johnson’s blog; he writes and hosts interviews and podcasts.
Kayce BasquesBlog of a software-based technical writer.

Stuff that pertains to other industries and specialties.

ℹ️ Information Architecture #

TitleNote
Types of software documentationArticle which explains the differences between product and process docs.
MECE Framework McKinseyThe 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 ResearchA group that publishes some of its UX findings for free.

🎙️ Journalism #

TitleNote
Help a ReporterTinder 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…

TitleNote
WIPO Patent Drafting ManualInternational standard
Upmath Online EditorGenerate 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.

TitleNote
API Learning ProcessResearch paper on how developers get acquainted with a new API.
Docs Like CodeIntroduction to the concept.

API Docs I like:

No better teacher than good examples. Copy and steal from the Old Masters.

Clearbit

  • 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.

Editors
Notepad++Great for simple text editing
VSCodeModern UX, customizable
Conventions
MarkdownSimplistic, quick, human-readable plain text.
AsciidoctorPlain-text for authoring technical layouts.
reStructured TextrST 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 FlareA long-standing contender.
Adobe FramemakerSame as above.
DoxygenSoftware documentation kit.
HerettoPreviously known as easyDITA.
PaligoCloud-based CCMS application.
Calencoentreprise 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 RobohelpI’m getting sick of typing “Adobe”.
Document360Markdown-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
ConfluenceJIRA integrated wiki and notes repository. Free if under 10 users.
SharePointIntegrated with OneDrive and hosts wiki/intranet portals.
NotionA note-taking and sharing system. Has a free tier.
NuclinoSimilar to Notion.
GuruCheatsheet style cards, works well with Slack chat.

📰 Design and Publish #

Crossover into graphic design and communication with visual mediums.

General
CanvaPre-made templates for print and social media.
Adobe PhotoshopFlexible and used for all kinds of graphics.
GIMPIt’s not as good as Photoshop for things like mockups, but it’s free.
Physical
Adobe InDesignThe current industry standard for print. Excellent control over typography and layout.
ScribusIt’s almost as good as InDesign for the unbeatable price of free.
MS Office PublisherCasual tool if you’re not a full-blown graphic designer.
Digital
Adobe IllustratorAn excellent program for creating clean illustrations for print or web, and even animations.
InkscapeA free program with a similar niche to Illustrator, but has poorer CMYK (print ink color) support. It’s better for creating SVG.
UI/UX
SketchShining paragon of UI/UX composition, but Mac-only requirement is limiting.
AxureHas advanced interaction capabilities for high-fidelity demos.
FigmaA free collaboration platform offered by Google.
Adobe XDSimilar to the above.
BalsamiqWireframe designer, low-fidelty and UX focused over UI.

📌 Business Process #

The stuff that you need to make your point (slide decks, demos).

Diagrams
Microsoft VisioFlowchart maker. Usually paid for by your company.
diagrams.net / draw.ioFree 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 TimelineIf you’re a paralegal, you probably need something like this.
JIRAProduct development management used in a lot of enterprises.
TrelloA lighter version of JIRA.
AsanaSimilar 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
SnagitScreenshot tool that lets you add arrows, blurs and callouts.
GreenshotOpen-source version of Snagit.
LICEcapFree, quick GIF screen capture utility
Video Recording
OBS StudioOpen-source, for recording and streaming.
CamtasiaBeginner-friendly screen capture program.
Post-processing
KdenliveOpen-source, free video editor.
OliveAn up-and-coming video editor aimed at the professional market. Still in beta but usable.
Davinci ResolveProfessional-grade video editor made by Blackmagic Design with a free and pro version.
Script
KIT ScenaristOpen-source script writing program.
CeltxScreenplay creation suite.

🤖 Automation #

If your department writes tests for UIs, get tech writers to become a stakeholder for test results, reports and screenshots.

Docs-as-code
Backstage TechdocsDeveloper Portal integrated docs.
AntoraMulti-repo aggregation documentation.
Pull Docs From Multi ReposMy own implementation available as a Powershell script.

OpenAPI Generators #

TitleNote
RapidocGenerate beautiful doc pages from OpenAPI spec; a modern successor to SwaggerUI.