Videos and articles¶
This page links to the topics that have been covered by conference talks or in the newsletter. They’re in no particular order, and some topics are repeated if they fit into more than one category. Enjoy!
If you think something is wrongly categorised, please send us a pull request :)
Writing words¶
- 🎥 Don’t Say Simply
- 🎥 Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan)
- 🎥 Information micro-architecture: grammar, syntax, and cognitive rhetoric
- 🎥 Writing as a non-native speaker
- 🎥 Writing So Your Words Are Read
- 🎥 Tone in Documentation
Naming and terminology¶
Specific writing questions¶
One word vs another, using abbreviations, etc.
- 📰 Gerunds in headings
- 📰 When to use acronyms
- 📰 And another thing! Referring to other documents
- 📰 Whether to say “please”
- 📰 Some discussions on style
- 📰 Should documentation have a formal tone?
- 📰 “You”-sing the second person in documentation
- 📰 The variable fortunes of variable placeholders in docs
- 📰 Using imperatives
- 📰 Page vs screen
- 📰 British vs American English
- 📰 Using abbreviations and acronyms
- 📰 Writing about unlabelled buttons
- 📰 Jokes in documentation
- 📰 The contrarian view: reasons to use “utilize”
Code samples¶
Formatting¶
Other media¶
Including videos, diagrams, and screenshots.
- 📰 Is written content outdated - and is it time for video?
- 📰 Command prompts in docs
- 📰 Tips for creating quality screenshots
- 🎥 Set your data free with model-based architecture diagramming
- 📰 Behind the scenes with fonts, emojis, and Unicode
- 📰 Advice for creating technical illustrations
- 📰 Tips and tricks for producing video
- 🎥 Draw the Docs
- 🎥 So you want to make videos?
- 🎥 Graphic Content Warning: The Pros, Cons, and Alternatives to Screenshots
- 📰 Automated screenshot-taking
- 🎥 Documentation beyond words
- 🎥 When bad screenshots happen to good writers
- 🎥 Screencasting 101
- 🎥 How to Write an Email
Writing topics¶
- 📰 Minimum viable documentation
- 📰 Toward a theory of technical writing?
- 📰 Can form follow function in techdoc?
- 📰 What to do with tricky little details
- 📰 Obvious things and whether to document them
- 📰 Types of docs and how to use them
- 📰 Choosing the right learning level for a topic
- 📰 Page length and user preference
- 🎥 Checklist the Docs
- 🎥 How to Write Documentation for People that Don’t Read
- 🎥 Engage or Die: Four Techniques for Writing Indispensable Docs
Task-based writing¶
API docs¶
- 🎥 Shuffle ball change: Sashay your way to clearer API documentation
- 🎥 Write the API docs before the API exists
- 📰 Documenting APIs with “interesting” design choices
- 📰 When does one API stop and another begin?
- 📰 API reference docs layout
- 📰 What do we mean by “API”
- 📰 Get started with API docs
- 🎥 So You Need to Document an API?
READMEs¶
In-app documentation¶
Release notes¶
Other specific doc types¶
Including how-tos, reference docs, tutorials, and books.
- 📰 Templates for concept documentation
- 🎥 How to write a book for (and with) an open source community
- 🎥 So you need to give bad news to users…
- 🎥 Writing a perfect technical tutorial
- 📰 To answer, or not to answer: FAQs
- 🎥 Emulating the Teacher’s Approving Nod in Teaching Material
- 🎥 How (and why) to make awesome video tutorials
- 🎥 Microcontent: Designing & Developing Reusable Content
- 🎥 Writing Backwards: Documenting the End-of-Life of a Product
- 🎥 Why SDK Docs Matter — And What I’m Doing About It!
- 🎥 The Power of Empathy in Support Documentation: A 5-Step Guide
- 🎥 101 to 404s: How to write great error messages
- 🎥 SDK Reference Manuals: A flow-based approach
- 🎥 “It’s a Feature” - Documenting Known Issues and Product Shortcomings
- 🎥 Writing the Next Great Tech Book
- 📰 Code comments and other musings on developer docs
- 🎥 The Facts About FAQs
- 🎥 Not the Docs: content and voice on a developer blog
- 🎥 “You never get a second chance to make a first impression”: writing great “getting started” documentation
- 🎥 Writing a book in 2017
- 🎥 Do you know a runbook from a flip book? How sysadmins use documentation
- 📰 Maintaining command reference pages
- 🎥 Code the Docs: Interactive Document Environments
- 🎥 The Federated Wiki
- 🎥 Designing Information for Growth
- 🎥 Blogging as Non-Traditional Support Documentation
- 🎥 What I learned writing a lousy tech book
Storytelling¶
- 🎥 When Wishing Still Helped … What Folklore Can Teach Us about Technical Writing
- 🎥 Storytelling for Technical Products - What We Can Learn from Lego and Pixar
- 🎥 Wild Geeks: Poetry in the Digital Age
- 🎥 Telling a Great Story on GitHub
- 🎥 What Writing Fiction Teaches You About Writing Documentation
- 🎥 Documenting your Story - Crafting a good presentation
- 🎥 Elevating the Hedgehog: Creativity in Tech Writing
- 🎥 Let’s Tell a Story: Scenario-Based Documentation
Writing doc sets¶
- 🎥 Don’t shoot yourself in the foot with content reuse
- 🎥 How to launch your startup with good docs
- 🎥 Delivering Documents For All Three Use Cases
- 🎥 What nobody tells you about documentation
Information architecture¶
- 📰 Where should support content live?
- 🎥 More than words: Reviewing and updating your information architecture
- 📰 Organizing docs by role, or by topic?
- 📰 A conversation about docs cleanup
- 📰 Information architecture resources
- 📰 Tagging docs
- 🎥 Building navigation for your doc site: 5 best practices
- 📰 Navigation tabs for different audiences
- 🎥 Information micro-architecture: grammar, syntax, and cognitive rhetoric
- 🎥 Search and find. How we made MDN discoverable
Legacy docs¶
- 🎥 Organizing a Confluence hoard, or, does this page spark joy?
- 🎥 Legacy content from various perspectives
- 🎥 When Agile Fails: Working on Large Documentation Projects
- 🎥 How to tear down existing documentation and rewrite docs that actually work
- 🎥 Tackling technical debt in the docs
- 🎥 Where do I start? The art and practice of documentation triage
- 🎥 Rewrite the Docs!: Field Notes from the Radical IT department
- 🎥 Deprecate and destroy: documenting your software’s last days
- 🎥 MacGyvering your docs
- 🎥 What Can Brownfield Do For You?
Maintenance¶
Jobs and careers¶
- 📰 Knowledge transfer for documentarians
- 📰 Joining as a manager
- 🎥 Hustling for Fun and Profit as a Technical Writer: A Freelancing Starter Kit
- 📰 Salary survey
- 📰 For those who might consider freelancing
Hiring¶
- 🎥 Fostering Technical Writing in Developing Nations
- 📰 Using writing tests when hiring
- 📰 Running objective interviews
- 📰 Developer to documentarian ratio
- 📰 Hiring and getting hired guide
- 🎥 Starting from Scratch: Finding and Hiring Junior Writers
- 🎥 Interviewing and hiring technical writers: the Siberian way
- 📰 Hiring for technical background
Getting hired¶
- 📰 Certifications and qualifications
- 📰 Breaking into tech writing
- 📰 Job listings and managing your assumptions
- 📰 Cover letters
- 📰 Hiring and getting hired guide
- 🎥 Document Yourself: Practical Tips for a Low(er)-Stress Portfolio
- 📰 Questions to ask at your job interview
- 📰 More questions to ask at your job interview
- 📰 Creating a doc portfolio
- 📰 Writing a resume
- 📰 Putting together a portfolio
Career growth¶
- 📰 Is coding necessary to write good docs?
- 📰 What’s in a (role) name, after all?
- 🎥 Beating the Virginia Blues: Thru-hiking strategies to help you survive your next big project
- 📰 Taking steps into leadership
- 🎥 Docs leadership: How to become a stronger leader for your team
- 🎥 From travel content to technical content: my journey
- 📰 A magnificent array of management topics
- 🎥 From Graffiti Writer to Technical Writer
- 🎥 Overcoming the Plight of Lone Writers
- 📰 Leading and following: finding a mentor, being a mentor
- 📰 Feeling like a fraud and how to deal with it
- 🎥 Fostering Talent: Mentorship, Peer Reviews and Going Beyond Your Job Description
- 📰 Making the leap to managing writers
- 🎥 Writer? Editor? Teacher?
- 🎥 Harvest Past Experience to be a Great Tech Writer
- 📰 Tips for lone writers starting from scratch
- 📰 Personal development goals
- 📰 Career paths
- 📰 Distinguishing between junior vs senior tech writers
- 📰 Alternative titles to technical writer
- 📰 Imposter syndrome
- 🎥 An Alien Looking From the Outside In: Main Takeaways After One Year in Documentation
- 📰 Job titles (real and imagined)
- 🎥 We’re Not in Kansas Anymore: How to Find Courage while Following the Technical Doc Road
- 🎥 IMPOSTER NO MORE: How Tech Writers Can Shed Self-Doubt, Embrace Uncertainty, and Surf the Upcoming Swerve in Technical Documentation
Building a team¶
Including onboarding new writers
Learning…¶
- 🎥 The Art of Asking Questions
- 📰 What we’re learning in #learn-tech-writing
- 🎥 Read the Rules: What technical writers can learn from board game design
- 📰 Learning regular expressions (regex)
- 📰 Book club: an intro to ‘Every Page is Page One’
- 📰 Learning material recommendations - fundamentals of tech writing, contenet strategy, API docs, Git
- 📰 #learn-tech-writing book club
- 📰 Learning tech writing
- 📰 Recommended books
- 📰 Learning Git
- 📰 Get started with API docs
Design and UX¶
Accessibility and inclusivity¶
- 🎥 ADHD and its impact on the Creative Process for Writers
- 🎥 Writing Documentation with Neurodivergent Open Source Contributors In Mind
- 🎥 Moving beyond empathy: a11y in documentation
- 📰 Resources for diverse example names
- 🎥 Inclusive environments are better: science says so
- 🎥 A11y-Friendly Documentation
- 📰 Accessibility for colour blindness
- 📰 Screen readers and svgs
- 🎥 Sticks & Stones… Microaggressions & Inclusive Language at Work
- 📰 Alt text best practices
- 📰 Improving diversity in docs
- 📰 Responsible communication guide
- 🎥 Accessible Math on the Web: A Server/Client Solution
- 🎥 Inclusive Tech Docs - TechComm Meets Accessibility
Localization and globalization¶
- 🎥 Creating documentation for the African audience
- 🎥 Toward the broader globalization of Open Source: documenting your localisation Journey
- 🎥 How I use applied linguistics to be a better technical writer
- 🎥 Influence your customer outreach with best practices for internationalization
- 🎥 Globalise the docs
- 🎥 Found in Translation: Lessons from a Year of Open Source Localization
- 🎥 Localize the Docs!
Design¶
- 🎥 When documenting is designing: How to assist API design as a technical writer
- 🎥 Surprise! You’re a designer now.
- 📰 Docs and design: When docs can’t fix all the things
- 🎥 How I decided to do this talk
- 🎥 Peanuts and Minimalism and Technical Writing
- 🎥 Writing for what matters. Writing for thinking.
- 🎥 We Are All Abbott and Costello
- 🎥 Designing Information for Growth
- 🎥 advanced web typography
UX writing¶
- 📰 Edge cases and when (and where!) to document them
- 🎥 Invisible influence — the documentation behind UX copy
- 🎥 Little words, big ideas: How to write microcopy that works
- 🎥 UX Writing - Let Your Product Speak
- 🎥 Creating experiences with information
- 🎥 Conversational UI for Writers
- 📰 Enforcing UI style guides
- 📰 Auditing UI text
- 📰 Writing error messages
- 🎥 Error Messages: Being Humble, Human, and Helpful will make users Happy
- 📰 Docs and content strategists
- 📰 What to include in UI copy
- 🎥 Using meaningful names to improve API-documentation
- 🎥 Watch that tone! Creating an information experience in the Atlassian voice
- 🎥 Copy That: Helping your Users Succeed with Effective Product Copy
- 🎥 Atlassian: My Information Experience Adventure
- 🎥 Before the docs: writing for user interfaces
- 🎥 Keep ‘em playing
Doc site design¶
- 🎥 A treasure map for the doc – Exploring the discoverability of documentation
- 🎥 Disagree with “I Agree”. Enforcing better data privacy through the language of documentation
- 🎥 Responsive Content - Presenting Your information On Any Device
- 📰 “Last updated” in docs
- 📰 Documentation bylines
- 📰 Meaningful URLs
- 📰 API reference docs layout
- 🎥 Code the Docs: Interactive Document Environments
- 📰 Can form follow function in techdoc?
User needs¶
- 🎥 The Baseline – Or Technical Writing for Non-Technical Readers
- 🎥 Seeing your docs through different eyes: Mapping doc users’ experiences
- 🎥 Documenting known unknowns
- 🎥 Requirements that you didn’t know were there
- 🎥 As Good As It Gets: Why Better Trumps Best
- 🎥 API documentation: Exploring the information needs of software developers
- 🎥 Documentation with Human Connection
- 🎥 User-Story Driven Docs
Doc tools¶
- 🎥 Two years of Markdoc: what we’ve learned about balancing developer and author experience
- 📰 Standards in documentation tooling
- 🎥 Hitchhiker’s Guide to Documentation Tools and Processes
- 🎥 Putting the “tech” in technical writer
- 🎥 Documentation as an application: enabling interactive content that is tailored to the user
- 🎥 Model-view-docs: taming large-scale documentation projects using structured data
- 🎥 The Rocky Road to DocOps
- 🎥 Don’t Fear Migration! How to Successfully Move Docs to a New Tool
- 🎥 Where Documentation, Cloud-hosted Interactive Tutorials and Continuous Integration Testing Intersect
- 📰 How your tools affect your writing
- 📰 Deciding on a new tool…
- 📰 … and migrating to a new tool
- 🎥 How I Learned to Stop Worrying and Love the Command Line
- 🎥 Choosing a tool… and choosing your moment
- 🎥 Writing extensions in Sphinx: supercharge your docs
- 🎥 Finally! Trustworthy and Sensible API Documentation with GraphQL
- 🎥 Embed The Docs
- 📰 Toolchains for docs
- 🎥 Challenges and approaches taken with the Opera Extension Docs
- 🎥 Writing multi-language documentation using Sphinx
- 🎥 Designing MkDocs
- 🎥 Going from Publican to Read the Docs
Docs-as-code¶
- 🎥 One AWS team’s move to docs as code: what worked, what didn’t, what’s next
- 📰 To git or not to git docs as code
- 📰 Pros and cons of the docs-as-code approach
- 🎥 The UK government meets docs as code
- 📰 Adventures in generating docs from code comments
- 📰 What to do about text wrapping
- 📰 DITA vs docs-as-code
- 📰 Moving to docs-as-code: static site generators
- 🎥 Workshop - Static Site Generators, What, Why and How
- 📰 Comparing static site generators
- 📰 Versioning docs with docs as code
- 📰 Making docs maintainable
- 📰 What are static site generators?
- 🎥 Treating documentation like code: a practical account
- 📰 Making Atom (even) better
- 📰 Tricks for static sites
- 🎥 Docs as Code: The Missing Manual
- 🎥 A Developers’ Approach to Documentation: From Passive to Dynamic
- 🎥 How GitHub uses GitHub to document GitHub
DITA¶
Automation¶
- 📰 Link-checking tools
- 🎥 Unit Test the Docs: Why You Should Test Your Code Examples
- 🎥 Beyond spell checking - what else can we check automatically?
- 🎥 Run your documentation
- 📰 Automated screenshot-taking
- 🎥 Testing: it’s not just for code anymore
- 🎥 Tech writing in a continuous deployment world
- 🎥 Tested and Correct, How to Make Sure Your Documentation Keeps Working
- 🎥 Generating docs from APIs
- 📰 Automation dreams - and realities
Git¶
Metrics and analytics¶
- 📰 Discovering user needs
- 🎥 Don’t trust the numbers!
- 🎥 The Importance of Using Analytics and Feedback for your Documentation
User research¶
- 🎥 Walking Backwards: Tracing the New Customer Journey from Finish to Start to Help Shape Content
- 📰 Starting out with analytics - and then upping your game
- 📰 Discovering user needs
- 🎥 Research like you’re wrong: Lessons from user research gone rogue
- 🎥 Building Empathy-Driven Developer Documentation
- 📰 UX testing documentation
- 🎥 API documentation: Exploring the information needs of software developers
- 🎥 We Are All Abbott and Costello
- 🎥 How to Write Documentation for People that Don’t Read
User feedback¶
Gathering it and acting on it.
Measuring docs success¶
Culture and community¶
- 🎥 A guide to getting started in open source
- 🎥 5 things I learned from my first open source contribution
- 🎥 A Year in the Life of The Better Docs Project
- 🎥 Technical writing as public service: working on open source in government
Building docs culture¶
- 🎥 Adventures in setting up a knowledge system for a research group
- 🎥 Almost None to Some: Driving DISQO’s Doc Culture as a Solo Documentarian
- 🎥 How to be an Avante-Garde Guinea Pig: Building Better Content through Experimentation, Community-building, and Loud Squeaks
- 🎥 Everyone’s a player (in a mid-90s MUD)
- 🎥 Documenting for Open Source
- 🎥 Defying the Status Quo: How a grassroots effort can transform an organization
- 🎥 Sponsored Talk: Documentation for Good: Knowledge as a tool for equity and inclusion
- 📰 Promoting plain language
- 📰 Common misconceptions about docs
- 🎥 Who Writes the Docs?
- 📰 Help your contributors help your project
- 📰 Crowdsourcing docs
- 🎥 Everyone’s a player (in a mid-90s MUD)
- 🎥 Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups
- 🎥 All roads might not lead to docs
- 🎥 Free Your Mind and Your Docs Will Follow
- 🎥 Documentation, Disrupted How Two Technical Writers Changed Google Engineering Culture, Built a Team, Made Powerful Friends, And Got Their Mojo Back
- 🎥 Entry points and guide posts: Helping new contributors find their way
- 🎥 The Making of Writing Black Belts: How Martial Arts Philosophy Forged an Ad-Hoc Writing Team that Writes Great Docs
Building community¶
- 🎥 Peer writing and beyond - An experimental approach to a sustainable open-source projects
- 🎥 All together now: Turning technologists into documentarians
- 🎥 Documentation Communities: Sound Strategy or Documentarian’s Gambit?
- 🎥 Helping Your Community Contribute to Developer Documentation
- 🎥 Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates
- 🎥 A content manager’s guide to crowdsourcing the docs
- 🎥 No Community Members Were Harmed in the Making of This Doc Sprint
- 🎥 The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization
- 🎥 Feedback handling, community wrangling, panhandling
- 🎥 Documentoring: Growing a “Love The Docs” community
- 🎥 How to Publish Wild-Caught Articles
- 🎥 Gardening Open Docs
- 🎥 The community wrote my docs!
Style guides¶
- 📰 Choosing a style guide
- 🎥 The Art of Consistency: Creating an in-house style guide
- 🎥 Building a style guide from the ground up: lessons learned from a lone writer
- 🎥 What They Don’t Tell You About Creating New Style Guides
- 📰 Enforcing UI style guides
- 📰 Style guides we like
- 📰 Improving diversity in docs
- 📰 Responsible communication guide
- 📰 One style guide for all types of writing?
- 🎥 Watch that tone! Creating an information experience in the Atlassian voice
- 🎥 Whatchamacallit: Controlled Vocabularies for Technical Writers
Working across roles¶
- 🎥 Cultivating a Stakeholder Network for Our Docs: How Building Relationships Improves Our Content
- 📰 The strengths of different backgrounds
Working with writers¶
Including review, editing, and teaching.
- 📰 What’s in a good reviewer’s guide?
- 🎥 Code Cowpokes and Word Wranglers: from Mutual Admiration to Solidarity
- 🎥 The Pains of Composition: How to write your best documentation in a collaborative world
- 📰 The challenge of giving difficult feedback
- 📰 Facilitating top-notch doc review
- 🎥 How to edit other people’s content without pissing them off
- 🎥 Good Code, Bad Code & Code Review
- 📰 Giving feedback
- 📰 Teaching peers writing
- 🎥 You have already succeeded: Design critique guidelines make feedback easier
- 🎥 How GitHub uses GitHub to document GitHub
Customer support¶
- 📰 Supporting documentation, documenting support
- 🎥 Power up your support team to create better documentation
- 🎥 Only Interesting Conversations: The symbiotic relationship between docs and support
- 🎥 Documentarians and Support: Work Better Together
- 🎥 Two Great Teams that Work Better Together: Bridging the Gap Between Documentation and Customer Support
Helping engineers to write¶
Working with other roles¶
Including product managers, higher-ups, etc.
- 📰 Improving communication about what’s in releases
- 🎥 Documentation as Marketing? From Conflict to Collaboration
- 🎥 Collaborating with teams on content strategy planning: pitfalls and best practices
- 📰 Getting more info from SMEs
- 🎥 An introduction to developer experience, and the role of a documentarian
- 🎥 The subtle art of interrogation
- 📰 Helping project managers understand docs
- 📰 Conflicts about what should be in the docs
- 📰 Writing good bug reports
- 🎥 Crossing the Streams: Enabling Collaboration Between Products and Upstreams
- 🎥 Writer, Meet Tester
- 🎥 Pairing with designers to create a seamless user experience
Planning and how we work¶
- 📰 Estimating docs work
- 📰 Estimating work
- 🎥 Alchemy in Adversity (How to become better and more resilient tech writers in a turbulent work environment)
- 📰 Adapting to working from home
- 🎥 Remote Job On-boarding: Top 10 Things We Can Do (Better)
- 📰 The costs of outdated docs
- 📰 How to set priorities on a documentation team
- 🎥 The Super Effective Writing Process of Grammy-winning Artists
- 📰 Writing remotely
- 📰 Roadmaps and documenting ‘future features’
Prioritisation¶
Agile and workflows¶
- 📰 Tracking work
- 🎥 Documenting the (Ancient) History of Your Project
- 🎥 Building a content-focused, scientific document authoring workflow for Data Scientists and Engineers alike
- 🎥 Lessons Learned in a Year of Docs-Driven Development
- 📰 Task management for docs teams
- 📰 Agile workflows for docs
- 📰 Working on Agile teams
- 📰 Changing docs workflows
- 📰 Automating routine tasks
- 🎥 Postulating The Backlog Laxative
- 🎥 Judas Priest Ate My Scrum Master
- 🎥 Your Personal Tech-Writing Agile Manifesto (or: Scrum is not a 4-character word)
Continuous delivery¶
- 📰 Agile delivery and continuous releases
- 🎥 Delivering High-Velocity Docs that Keep Pace with Rapid Release Cycles
- 🎥 Continuous Annoyment: Bringing More Zen to a Hectic Writing Environment
- 🎥 Just-In-Time Documentation: Employing Agile Methodology To Create Living Documentation
- 🎥 Keeping trust: Testing documentation as part of a continuous integration process
Strategy¶
- 🎥 Lessons Learned from Cloud Ops: Writing Docs for High-Stakes Situations
- 🎥 Always complete, never finished
- 🎥 Beyond metrics: Using maturity models to develop a docs strategy
- 🎥 Content strategy in practice: a case study
- 🎥 Show Me the Money: How to Get Your Docs the Love and Support They Deserve
- 🎥 Backseat content strategy
- 🎥 Product Documentation Strategy: What Is It and Why Do We Need It?
- 🎥 Choosing a tool… and choosing your moment
- 🎥 Audience, Market, Product: Tips for strategic API documentation planning
- 🎥 Bootstrapping Docs at a Startup
- 📰 Making docs maintainable
- 🎥 Designing Information for Growth
Defining success¶
Theories/Philosophy¶
Maths, science and history¶
- 🎥 The Secret History of Libraries
- 🎥 A Journey to Pattern Languages
- 🎥 Facebook, Dynamite, Uber, Bombs, and You
- 🎥 A brief history of text markup languages
- 🎥 Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time
- 🎥 Intelligent Documents and the Verifiability Crisis in Science
- 🎥 Accessible Math on the Web: A Server/Client Solution
- 🎥 The quest for scientific credit for software documentation
- 🎥 Back to the Future: What Can Documentarians Learn From The Past?
- 🎥 A brief history of math writing: symbol, structure, and proof
