Product & Technical
Technical Writing
Technical writers turn engineering knowledge into documentation people can act on. It is one of the few well-paid technology careers genuinely open to people from a humanities background, provided they are willing to become technically literate.
Start here
Find documentation that confused you recently and rewrite one page of it. That artefact is worth more than any certificate on this path, and you can produce it this week.
Writing craft
The foundation. Technical accuracy without clarity helps nobody.
RequiredWriting clearly
Documentation is read by someone who is stuck, impatient and possibly reading in a second language. Every unnecessary word costs.
Writing clearly
Documentation is read by someone who is stuck, impatient and possibly reading in a second language. Every unnecessary word costs.
What to learn
- Plain language
- Active voice
- Short sentences and one idea each
- Cutting ruthlessly
- Consistent terminology
- Writing for a reader whose first language is not English
Practice
Next: Knowing who you are writing for.
RequiredAudience and document types
The single most common documentation failure is answering a different question from the one the reader has.
Audience and document types
The single most common documentation failure is answering a different question from the one the reader has.
What to learn
- Tutorials versus how-to guides versus reference versus explanation
- Identifying the reader's actual task
- Assumed knowledge, stated explicitly
- Progressive disclosure
- Structuring for scanning rather than reading
Practice
Next: Enough technical knowledge to be accurate.
Technical literacy
You do not need to be an engineer. You do need to read code and use the thing you are documenting.
RequiredTechnical fundamentals
Writers who cannot run the product write documentation that does not work, and engineers stop trusting them.
Technical fundamentals
Writers who cannot run the product write documentation that does not work, and engineers stop trusting them.
What to learn
- Command line basics
- Git and pull requests
- Reading code without writing it
- APIs and HTTP
- Understanding an error message
- Running the product locally
Tools
- Git
- A terminal
- An API client
Practice
Next: Documenting APIs.
RequiredAPI documentation
The highest-demand and best-paid specialism in technical writing.
API documentation
The highest-demand and best-paid specialism in technical writing.
What to learn
- OpenAPI specifications
- Endpoint reference structure
- Authentication documented properly
- Request and response examples that actually run
- Error reference
- Quickstarts that work in five minutes
Tools
- OpenAPI
- Postman
- A docs generator
Project
intermediateAPI documentation from scratch
Document a public API that is poorly documented: a quickstart, full endpoint reference, authentication guide, and runnable examples in two languages.
- OpenAPI
- Markdown
- A static docs site
A developer could integrate with that API using only your documentation.
Next: The tooling writers actually use.
Docs as code
How modern documentation is written, reviewed and published.
RequiredThe docs-as-code workflow
Documentation living in the repository, reviewed in pull requests, published by CI, is now the standard expectation.
The docs-as-code workflow
Documentation living in the repository, reviewed in pull requests, published by CI, is now the standard expectation.
What to learn
- Markdown and MDX
- Static site generators
- Version control for content
- Review workflow
- Automated link checking and linting
- Versioned documentation for multiple releases
Tools
- Markdown
- Docusaurus, MkDocs or similar
- Git
- Vale for style linting
Next: Illustrating it.
RecommendedDiagrams and examples
A diagram can replace three paragraphs, and a runnable example replaces the rest.
Diagrams and examples
A diagram can replace three paragraphs, and a runnable example replaces the rest.
What to learn
- Architecture diagrams
- Sequence diagrams
- Diagrams as code so they stay current
- Code samples that are tested
- Screenshots and their maintenance burden
Tools
- Mermaid
- draw.io
Next: Working with the people who know things.
Working as a technical writer
The professional practice around the writing.
RequiredWorking with engineers
Your sources are busy people who find documentation an interruption. Making it easy for them is a real skill.
Working with engineers
Your sources are busy people who find documentation an interruption. Making it easy for them is a real skill.
What to learn
- Interviewing an engineer efficiently
- Drafting first and asking for correction rather than explanation
- Reviewing pull requests for documentation impact
- Getting into the release process early
- Handling contradictory sources
Practice
Next: Maintaining it.
RequiredDocumentation architecture and maintenance
Documentation rots. A site nobody can navigate is as useless as one that is out of date.
Documentation architecture and maintenance
Documentation rots. A site nobody can navigate is as useless as one that is out of date.
What to learn
- Site structure and navigation
- Search and findability
- Style guides
- Deprecation and archiving
- Measuring what is read and what is not
- Feedback loops from readers
Project
advancedDocumentation for a real project
Adopt an open source project with weak documentation. Restructure it, write a working quickstart, add a how-to section, set up automated link checking, and get it merged.
- Git
- Markdown
- A docs framework
You have merged documentation into a project used by strangers, which is the portfolio piece this field actually respects.
Where this leads
You do not have to pick one now. These are the directions this path opens up once you are working.
Continue your journey
The paths closest to this one. Skills overlap more than the job titles suggest.
Developer Relations
Help developers succeed with a product, and bring their problems back.
ViewProduct Management
Decide what gets built, why, and what gets cut.
ViewUI/UX Design
Decide how something should work before anyone builds it.
ViewSoftware Engineering
Write code other people can read, run and rely on.
ViewYou do not have to do this alone
Our programs are free, taught live, and built around the same progression. Join one and work through it alongside other people.