All our 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.
Code samples¶
Formatting¶
Other media¶
Including videos, diagrams, and screenshots.
Writing topics¶
- 📰 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 Indispensible Docs
Task-based writing¶
API docs¶
READMEs¶
Other specific doc types¶
Including how-tos, reference docs, tutorials, and books.
- 🎥 Learning to love release notes
- 🎥 “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
Writing doc sets¶
Information architecture¶
- 📰 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¶
- 🎥 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¶
Hiring¶
Getting hired¶
Career growth¶
- 📰 Making the leap to managing writers
- 📰 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)
- 📰 Exploring other careers
- 📰 Learning tech writing
- 📰 Recommended books
- 📰 Learning Git
- 📰 Get started with API docs
- 🎥 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
Design and UX¶
Accessibility and inclusivity¶
- 🎥 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
Design¶
UX writing¶
- 🎥 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¶
Doc tools¶
- 🎥 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¶
- 📰 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¶
Git¶
Metrics and analytics¶
User research¶
- 📰 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 Year in the Life of The Better Docs Project
- 🎥 Technical writing as public service: working on open source in government
Building docs culture¶
- 📰 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¶
- 🎥 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
- 🎥 Healthy Minds in a Healthy Community
- 🎥 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¶
- 🎥 The Art of Consistency: Creating an in-house style guide
- 🎥 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¶
Working with writers¶
Including review, editing, and teaching.
Customer 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.
- 🎥 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¶
Prioritisation¶
Agile and workflows¶
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¶
Defining success¶
Theories/Philosophy¶
Maths, science and history¶
- 🎥 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
