Documentation and technical writing resources, including local resources for documentarians in Toronto and Ontario.
Learn to write more clearly
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
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 role
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
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.
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.
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.
Tom Johnson has a guide for writers and engineers on Documenting APIs.
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.
Code of conduct and community guidelines
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
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.
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.
Sharing knowledge ranked as the top problem area
DevOps Research and Assessment (DORA)
Research by DORA found that a culture of learning contributes to improved organizational performance and strong team culture.
State of DevOps Report 2019 on 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