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

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.

  • 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

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.

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

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.

Doc accessibility

Writing guidance

General accessibility guidance

Local Toronto resources

Doc communities

Data on doc usage

This is a list of surveys and research that referenced in my talks.

  • Open Source Survey 2017

    • 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

    • 2018 - Docs are the primary way that developers learn on their own

    • 2016 - Poor documentation ranked as the second biggest challenge at work

  • Mozilla Web DNA Report 2019

    • 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)

    • 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