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.
- π° 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
EditingΒΆ
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ΒΆ
- π° 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?
MaintenanceΒΆ
Jobs and careersΒΆ
HiringΒΆ
- π° 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ΒΆ
- π° 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ΒΆ
- π° 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ΒΆ
- π₯ 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ΒΆ
- π° DITA vs docs-as-code
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ΒΆ
MetricsΒΆ
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!
MeetupsΒΆ
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.
- π° 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.
- π° 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ΒΆ
- π° 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