Content Archive by Topic¶
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 categorized, please let us know.
Writing words¶
🎥 Aw Snap! The Docs, They Are A-Changin’ (with apologies to Bob Dylan)
🎥 Information micro-architecture: grammar, syntax, and cognitive rhetoric
Grammar¶
Naming and terminology¶
Specific writing questions¶
One word vs another, using abbreviations, etc.
Editing¶
Code samples¶
Formatting¶
Other media¶
Including videos, diagrams, and screenshots.
Writing topics¶
Task-based writing¶
API docs¶
READMEs¶
In-app documentation¶
Release notes¶
Other specific doc types¶
Including how-tos, reference docs, tutorials, and books.
🎥 How to write a book for (and with) an open source community
🎥 Emulating the Teacher’s Approving Nod in Teaching Material
🎥 Writing Backwards: Documenting the End-of-Life of a Product
🎥 The Power of Empathy in Support Documentation: A 5-Step Guide
🎥 “It’s a Feature” - Documenting Known Issues and Product Shortcomings
🎥 Do you know a runbook from a flip book? How sysadmins use documentation
Storytelling¶
Writing doc sets¶
Information architecture¶
Legacy docs¶
🎥 Organizing a Confluence hoard, or, does this page spark joy?
🎥 How to tear down existing documentation and rewrite docs that actually work
🎥 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
Maintenance¶
Jobs and careers¶
Hiring¶
Getting hired¶
Career growth¶
🎥 Beating the Virginia Blues: Thru-hiking strategies to help you survive your next big project
🎥 Docs leadership: How to become a stronger leader for your team
🎥 Fostering Talent: Mentorship, Peer Reviews and Going Beyond Your Job Description
🎥 An Alien Looking From the Outside In: Main Takeaways After One Year in Documentation
🎥 We’re Not in Kansas Anymore: How to Find Courage while Following the Technical Doc Road
Building a team¶
Including onboarding new writers
Learning…¶
Design and UX¶
Accessibility and inclusivity¶
Localization and globalization¶
🎥 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
🎥 Found in Translation: Lessons from a Year of Open Source Localization
Design¶
UX writing¶
Doc site design¶
User needs¶
Doc tools¶
🎥 Two years of Markdoc: what we’ve learned about balancing developer and author experience
🎥 Documentation as an application: enabling interactive content that is tailored to the user
🎥 Model-view-docs: taming large-scale documentation projects using structured data
🎥 Don’t Fear Migration! How to Successfully Move Docs to a New Tool
🎥 Where Documentation, Cloud-hosted Interactive Tutorials and Continuous Integration Testing Intersect
🎥 Finally! Trustworthy and Sensible API Documentation with GraphQL
🎥 Challenges and approaches taken with the Opera Extension Docs
Docs-as-code¶
DITA¶
AI and LLMs¶
Automation¶
Git¶
Search¶
Metrics and analytics¶
User research¶
User feedback¶
Gathering it and acting on it.
Measuring docs success¶
Metrics¶
Culture and community¶
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
🎥 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
🎥 Move Fast And Document Things: Hard-Won Lessons in Building Documentation Culture in Startups
🎥 Entry points and guide posts: Helping new contributors find their way
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
🎥 No Community Members Were Harmed in the Making of This Doc Sprint
🎥 The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization
Meetups¶
Style guides¶
Working across roles¶
Working with writers¶
Including review, editing, and teaching.
🎥 Code Cowpokes and Word Wranglers: from Mutual Admiration to Solidarity
🎥 The Pains of Composition: How to write your best documentation in a collaborative world
🎥 How to edit other people’s content without pissing them off
🎥 You have already succeeded: Design critique guidelines make feedback easier
Customer support¶
Helping engineers to write¶
Working with other roles¶
Including product managers, higher-ups, etc.
📰 How to make your work as a documentarian shine: Beyond “just writing docs”
🎥 Documentation as Marketing? From Conflict to Collaboration
🎥 Collaborating with teams on content strategy planning: pitfalls and best practices
🎥 An introduction to developer experience, and the role of a documentarian
🎥 Crossing the Streams: Enabling Collaboration Between Products and Upstreams
🎥 Pairing with designers to create a seamless user experience
Planning and how we work¶
Prioritisation¶
Agile and workflows¶
Continuous delivery¶
🎥 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
🎥 Beyond metrics: Using maturity models to develop a docs strategy
🎥 Show Me the Money: How to Get Your Docs the Love and Support They Deserve
🎥 Product Documentation Strategy: What Is It and Why Do We Need It?
🎥 Audience, Market, Product: Tips for strategic API documentation planning
Defining success¶
Theories/Philosophy¶
Maths, science and history¶
🎥 Tech Writers Without Borders: Making the world a better place, one (numbered) step at a time
🎥 Intelligent Documents and the Verifiability Crisis in Science
🎥 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
