Technical Writing: What the Work Involves and How to Break In

What freelance technical writers produce, the tools and style guides clients expect, and how to build a first portfolio

Technical writing turns complex products into instructions a non-expert can follow: user guides, knowledge base articles, API references, and onboarding tutorials. Most freelance work is ongoing rather than one-off, because documentation has to be revised every time a product changes. Domain familiarity matters more than an engineering degree.

What does a freelance technical writer actually produce?

Four deliverables account for most freelance technical writing, and they are not interchangeable. A user guide walks someone through a complete task from start to finish. A knowledge base article answers one specific question that somebody typed into a search box, and has to make sense with no surrounding context. An API reference is a precise contract a developer reads while writing code against it. An onboarding tutorial exists to get a new customer to a first success quickly, which means cutting everything that is true but not yet useful.

• User guides and how-to articles, which walk a reader through a complete task
• Knowledge base and help center articles, written to be found by search and read in isolation
• API reference documentation, usually generated from an OpenAPI specification and then edited for clarity
• Release notes and changelogs, which state what changed and what the reader has to do about it
• Onboarding tutorials and quickstarts, aimed at a first success within minutes

Most engagements involve more than one of these. A company that hires a writer for release notes usually discovers within a month that its quickstart is also out of date.

What tools do clients expect you to work in?

Most teams work in one of a handful of documentation environments, and the brief normally names which. Learning one well is enough to start, because the writing skill transfers and the tooling itself takes days rather than months to pick up.

• MadCap Flare, a dedicated help-authoring tool common in enterprise and regulated industries
• Confluence, where documentation often sits alongside internal engineering notes
• Docs-as-code: Markdown files in a Git repository, built with a static site generator such as Docusaurus or MkDocs and reviewed through pull requests
• Help center platforms such as Zendesk or Intercom, where customer-facing support articles are published
• OpenAPI, formerly Swagger, which generates the skeleton of an API reference that a writer then edits into something readable

Docs-as-code deserves particular attention because it changes the job. Your drafts go through the same pull request review as engineering work, which means basic Git literacy — create a branch, commit, open a pull request, respond to review comments — is increasingly assumed rather than taught. Writers who can work this way are considered for projects that others are filtered out of.

Which style guide will you be asked to follow?

Most software companies standardise on one of two public style guides, and fluency in either is a concrete credential you can name in a pitch. The Microsoft Writing Style Guide is the most widely adopted across enterprise software. The Google developer documentation style guide is more common at developer-tools and infrastructure companies. Both are published free online, and both settle the questions that come up constantly: whether to address the reader as you, sentence case or title case for headings, how to refer to interface elements, and when a procedure should become a numbered list.

Read whichever matches the companies you want to work with before your first project rather than during it. Style disagreements discovered in review are expensive, and an editor notices immediately whether a writer has internalised the house guide.

Do you need an engineering background?

No. What clients pay for is clarity, structure, and the patience to keep asking what something actually means until you understand it well enough to explain it to someone who does not. Domain familiarity helps and compounds over time — a writer who already understands payment processing or clinical workflows needs fewer rounds with subject-matter experts — but it is built through projects rather than degrees.

The skill that most separates competent technical writers from struggling ones is interviewing. Nearly all documentation is produced by extracting knowledge from an engineer or product manager who has very little time and no instinct for what a beginner does not already know. Good questions asked in a focused thirty-minute call are worth more than a full day of guessing from a product demo.

How do you build a technical writing portfolio with no clients?

Write documentation for software you already use. Nobody has to hire you first, and an editor assessing a sample cares whether it is clear, not whether it was paid for.

• Pick a tool you use daily and write the setup guide you wish had existed when you started
• Find an open-source project with weak documentation and contribute a page; the contribution is public, timestamped, and verifiable
• Take a badly written help article, rewrite it, and publish both versions with a short note explaining what you changed and why
• Document a single API endpoint properly, covering the request, the response, the error cases, and one working example

Two or three samples are enough. Three pieces that demonstrate judgement are worth more than twenty that demonstrate availability, and the note explaining your reasoning is often what gets read most closely.

What makes a documentation project go badly?

Three failure modes account for most of it, and all three are visible before you accept the work if you ask. If nobody can tell you who will answer your questions, the schedule is already fiction.

• No access to a subject-matter expert, which turns a two-week project into two months of inference
• Undefined scope, where a brief to document the product expands without any agreed stopping point
• No agreed home for the finished content, so approved drafts sit unpublished in a shared document
• Screenshots commissioned before the interface is final, which guarantees rework

What does the work look like week to week?

Technical writing is maintenance-heavy, which is why it tends toward long relationships rather than one-off projects. A typical week mixes new drafting with revision: a walkthrough for a feature shipping next month, an update to an existing article because a screen changed, an interview for release notes. Once a company finds a writer who understands its product, replacing that person is genuinely expensive, so engagements tend to run long and renew quietly.

How do you get started?

Build two samples on software you already know well, learn one documentation environment thoroughly enough to discuss it in an interview, and read whichever of the two major style guides matches the companies you are targeting. Then apply to companies that publish their documentation publicly. You can read what they already have, identify what is missing or unclear, and say so specifically. Specific observations about someone's actual documentation are the single most effective thing to put in a pitch, and almost nobody does it.