Resources
Documentation and technical writing resources, including local resources for documentarians in Toronto and Ontario.
Learn to write more clearly
Writing fundamentals
Google Technical Writing site - Free courses that cover technical writing fundamentals for engineers, writing resources, and information about the technical writing role. The education is based on the same education Google offers to software engineers
Tech writing programs
Toronto
Waterloo
Undergraduate Minor in Technical writing and Technical Writing specialization
Masters in Rhetoric and Communication Design
Some related communication programs and programs in other areas of Ontario are listed on the STC Toronto Education page.
Learn about the tech writing and doc practices
Docs for Developers: An Engineer's Field Guide to Technical Writing - A book specifically written to help developers navigate the full doc lifecycle
The Product is Docs - An e-book by Splunk tech writers that describes modern doc practices in software.
Docs or it didn't happen - A talk at DevOps Days Galway that clearly describes why docs are central to software development, and how Google makes docs a part of normal engineering work
Technical writing at Google
Software Engineering at Google - A book that covers Software Engineering practices at Google, with a chapter devoted to documentation. Many tech writers at Google who work on developer docs use the same tools as the software engineers for things like issue tracking, source control, and reviews.
Templates, tools, and style guides
There are lots of formats for docs, and choosing a format depends on numerous factors including the volume of docs, the skills of the contributors and reviewers, how often docs need to be updated, the formats you need to provide to your users, level of integration with code builds, and whether docs are published manually are are part of an automated build process.
Templates and tools
If using a wiki or Google docs works for you, that's fine. The following resources are examples of tools designed for docs in open source or docs that follow a docs-as-code model.
Docsy - A Hugo theme for technical docs.
Antora - A site generator that uses AsciiDoc as source. It is specifically designed for technical docs built with automated pipelines. It's a relatively young tool, but is quickly gaining popularity among tech writers.
Good Docs Project - Best practice templates and writing instructions for documenting open source software.
Docs Like Code - Anne Gentle's site, where you can buy her Docs Like Code book or learn about various use cases for different docs-as-code implementations in the Learn section.
Style guides
Google developer documentation style guide
Microsoft style guide
Tools to help you create Markdown docs
If you want to use Markdown as your source, but have some contributors who aren't comfortable working in Markdown, these tools may help.
Typora - A Markdown editor that directly supports Markdown syntax but is accessible to new Markdown authors. Displays your text like a rich editor. It's a nice way to support both experienced Markdown authors and those who are new to Markdown.
Docs to Markdown - Google Drive add-on to convert a Google Doc to Markdown.
Develop your technical skills
Some resources for writers looking to learn some technical skills
Coding, HTML, CSS
Python is one of the most approachable languages for those new to programming.
Automate the Boring Stuff is recommended regularly in the Write the Docs community. Available as a book and Udemy course. There's also a Udemy course on Python for Absolute Beginners.
If you want to learn some bash, Bandit is a game aimed at teaching those new to bash.
Canada Learning Code is a non-profit that offers workshops for a variety of skills including coding, HTML, and CSS.
APIs
Tom Johnson has a guide for writers and engineers on Documenting APIs.
Git
The most common source control repository used in open source.
Learn Git in a Month of Lunches is recommended by several members of the Write the Docs community
Get involved with open source
Google Season of Docs - A program that pairs tech writers and open source projects for 3-6 months.
Local Toronto success story
Write the Docs Slack - Includes a #community-help-wanted channel to connect writers with open source projects.
Tips from Sarah Maddox on organizing a doc sprint.
Building inclusive projects with docs
Missing, obsolete, or inaccurate docs are consistently cited as a top pain point for developers (e.g. GitHub 2017 Open Source survey, Mozilla Web DNA Report 2019). The Open Source Survey also found that projects that clearly explain project processes were more welcoming to underrepresented groups.
So contributing to project docs helps everyone. And ensuring that your project has docs that clearly set ground rules helps everyone to feel welcome.
GitHub Best Practices for Maintainers and Building Welcoming Communities provides good info for inclusive, welcoming projects
Code of conduct and community guidelines
Google Open Source community guidelines
Doc accessibility
Writing guidance
General accessibility guidance
Web Accessibility in Mind - Lots of great articles about making your web content more usable for everyone.
Web design patterns and components
a11ysupport.io - Learn about what HTML attributes are supported by screen readers.
Local Toronto resources
#a11yTO - Runs meetups and conferences
Fable Labs - A community of users with disabilities in research and user testing who can help you with accessibility testing
Command line interface accessibility
Doc communities
Write the Docs - A community open to anyone interested in documentation.
API the Docs - Like Write the docs, but focused on APIs.
Society for Technical Communication (STC) - An organization focused on technical communication. Resources are available to members.
Toronto chapter
Data on doc usage
This is a list of surveys and research that referenced in my talks.
Incomplete or confusing docs ranked as the top problem in open source, but docs are largely neglected.
Docs were also important for creating a welcome environment for people from underrepresented groups.
Stack Overflow Developer Survey
Outdated or inaccurate documentation for frameworks and libraries was ranked as the second most frustrating area.
CodingSans Software Development Trends 2019 and 2020
Sharing knowledge ranked as the top problem area
DevOps Research and Assessment (DORA)
State of DevOps Report 2021 includes findings on doc quality and its positive impact on team performance
State of DevOps Report 2019 includes the impact of finding the info you need:
Organizations that invest in effective internal search are:
1.73 times more likely to be productive.
Contribute to a virtuous cycle of knowledge sharing
People that leverage external search:
1.67 times more likely to report feeling productive
Research by DORA found that a culture of learning contributes to improved organizational performance and strong team culture.