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.
- 📰 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
Code samples¶
Formatting¶
Other media¶
Including videos, diagrams, and screenshots.
- 📰 Command prompts in docs
- 📰 Tips for creating quality screenshots
- 📰 Behind the scenes with fonts, emojis, and Unicode
- 📰 Advice for creating technical illustrations
- 📰 Tips and tricks for producing video
- 🎥 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¶
- 📰 Toward a theory of technical writing?
- 📰 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¶
READMEs¶
Other specific doc types¶
Including how-tos, reference docs, tutorials, and books.
- 📰 To answer, or not to answer: FAQs
- 📰 Do we tell users what’s new in the docs?
- 🎥 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¶
- 📰 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¶
- 🎥 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?
Jobs and careers¶
Hiring¶
Getting hired¶
- 📰 Certifications and qualifications
- 📰 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?
- 📰 A magnificent array of management topics
- 📰 Leading and following: finding a mentor, being a mentor
- 📰 Feeling like a fraud and how to deal with it
- 📰 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
- 🎥 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
Learning…¶
- 📰 What we’re learning in #learn-tech-writing
- 📰 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¶
- 📰 Resources for diverse example names
- 🎥 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¶
- 📰 Edge cases and when (and where!) to document them
- 🎥 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¶
- 📰 How your tools affect your writing
- 📰 Deciding on a new tool…
- 📰 … and migrating to a new tool
- 🎥 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¶
- 📰 To git or not to git docs as code
- 📰 Pros and cons of the docs-as-code approach
- 📰 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¶
Metrics and analytics¶
User research¶
- 📰 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 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
- 🎥 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.
- 📰 What’s in a good reviewer’s guide?
- 📰 The challenge of giving difficult feedback
- 📰 Facilitating top-notch doc review
- 🎥 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
- 📰 Getting more info from SMEs
- 🎥 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 work
- 📰 Adapting to working from home
- 📰 The costs of outdated docs
- 📰 How to set priorities on a documentation team
- 📰 Writing remotely
- 📰 Roadmaps and documenting ‘future features’
Prioritisation¶
Agile and workflows¶
- 📰 Tracking work
- 📰 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¶
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
