Tag Archives: technical writing

Season of Docs announces 2020 technical writing projects

Season of Docs has announced the technical writers participating in the program and their projects! You can view a list of organizations and technical writing projects on the website.

The program received over 500 technical writer applications, and with them, over 800 technical writing project proposals. The enthusiasm from the technical writing and open source communities has been amazing!

What is next?

During the community bonding period from August 17 to September 13, mentors must work with the technical writers to prepare them for the doc development phase. By the end of community bonding, the technical writer should be familiar with the open source project and community, understand the product as a whole, establish communication channels with the mentoring organization, and set clear goals and expectations for the project. These are critical to the successful completion of the technical writing project.

Documentation development begins on September 14, 2020.

What is Season of Docs?

Documentation is essential to the adoption of open source projects as well as to the success of their communities. Season of Docs brings together technical writers and open source projects to foster collaboration and improve documentation in the open source space. You can find out more about the program on the introduction page of the website.

During the program, technical writers spend a few months working closely with an open source community. They bring their technical writing expertise to the project's documentation and, at the same time, learn about the open source project and new technologies.

The open source projects work with the technical writers to improve the project's documentation and processes. Together, they may choose to build a new documentation set, redesign the existing docs, or improve and document the project's contribution procedures and onboarding experience.

General timeline
August 16Google announces the accepted technical writer projects
August 17 - September 13Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors
September 14 - December 5Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period
January 6, 2021Google publishes the list of successfully-completed projects

See the full timeline for details, including the provision for projects that run longer than three months.

Find out more

Explore the Season of Docs website at g.co/seasonofdocs to learn more about the program. Use our logo and other promotional resources to spread the word. Check out the FAQ for further questions!

By Kassandra Dhillon and Erin McKean, Program Managers, Google Open Source Programs Office

Teaching the art of great documentation

Posted by James Scott, Technical writer

Technical writing is simple - you merely have to explain brutally complex technologies to relentlessly unforgiving audiences. It's unsurprising that so many engineers find writing documentation is the most painful part of their job. If you would like to teach your colleagues to become writers, the good news is Google's fun and interactive technical writing course materials are free and available for everyone to use! Alternatively, if you're a developer who would like to learn how to write more clearly, you can read through the course work for yourself or convince a colleague to teach the course at your organisation!

We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words. Our self-paced and facilitator-led courses will not only help software engineers choose the right words but also help to make the whole writing process a lot less scary. Perhaps software engineers won't become William Shakespeare or even William Shatner overnight, but hopefully they will gain the confidence to write something worth publishing. As working from home becomes more common, good documentation has never been more important in enabling software engineers to work independently.

Courses overview

Google introduced the technical writing courses, Technical Writing One and Technical Writing Two, in 2015. Since then, thousands of Google software engineers and product managers have taken and enjoyed the courses. In February 2020, we released the courses to the world.

The classes have the following structure:

  • Students complete self-study work before attending the live class. The self-study work is valuable on its own, even for students who will never attend the live class.
  • A facilitator guides students through a live class. The live class features practical exercises, class discussion, and extensive peer-to-peer feedback. Note that Google does not lead these live courses but provides extensive material to help facilitators prepare to lead them.

Organizations can choose to host the live classes virtually or in-person.

Technical Writing One

The first course, Technical Writing One, covers the basics of technical writing. Students learn to start thinking about their audience before even putting pen to paper. For example, in one exercise, students are challenged to write instructions for putting toothpaste on a toothbrush. That might sound relatively simple, but here's the catch - your audience has never brushed their teeth before. That's not to say they have bad oral hygiene, but they don't even know what a toothbrush is. The exercise aims to get students to think about documenting a completely new technology.

Another important lesson that Technical Writing One teaches you is how to shorten the sentence length in your documentation and how to edit unnecessarily long sentences. Hopefully once you have taken the course, you might edit the preceding sentence down to something like the following: Another important lesson that Technical Writing One teaches you is to shorten sentences length in your documentation and how to edit unnecessarily long sentences.

The course also advocates using lists instead of walls of text, so here, in list form, are some other topics it covers:

  • Using active voice instead of passive voice.
  • Revising text into clear paragraphs.
  • Learning various self-editing techniques.

Technical Writing Two

Technical Writing Two builds on the techniques from the first course and is for those who already know verbs from adverbs. The course encourages students to express their creative side. For example, in one exercise, students find the best way to illustrate technical concepts. Spoiler alert: can you spot any issues with the following diagram?

A diagram titled Finding a website through DNS, with seven boxes of varying colour, size, and shape connected by lines in various directions.

Figure 1: Finding a website through DNS

Other intermediate techniques the course covers include:

  • Organizing large doc sets.
  • Revising and reorganizing text.
  • Writing accurate descriptions.
  • Creating tutorials for beginners.

Students take part in interactive exercises and peer review with a lab partner. Technical Writing Two also includes class discussions on documentation types and how to write the dreaded first draft.

Want to know more?

If you would like to teach the courses at your own organization, see the facilitator guides. To review the pre-work and read through the training materials, see the course overviews.

Insights from mixing writers with open source

The OSGeo Foundation participated in Google’s first Season of Docs, where Google sponsored technical writers to contribute to open source projects. The Open Geospatial Foundation (OSGeo), is an umbrella organization for around 50 geospatial open source projects. I’ve contributed to a number of these projects over the years and co-mentored the two Season of Docs technical writers allocated to us.
Screenshot from the OSGeoLive distribution we've been documenting, available under a CC-By license.
During our involvement we discovered that, like many open source projects, we knew little about:
  • The state of our docs.
  • What we were aiming for.
  • What our priorities were.
  • The details of the challenges we faced.
  • How to improve.
We learned:
  • How hard it is to keep tech docs current.
  • Skillsets from multiple roles are needed to create good docs.
  • Open source’s docs and writing processes are immature when compared to software development.
It is an exciting problem space with high-value challenges ready to be tackled. It reminds me of the early days of open source before it became trendy with business.

What should tech writers work on?

Open source communities welcomed the chance to have tech writers improve our docs, and expressed a pressing need for it, but found it challenging to articulate what exactly needed fixing.
  • People explained that their project docs often hadn’t been updated between doc releases.
  • Some projects had noticed new features that had not been documented.
  • Other projects had issue lists—collating observed deficiencies—but had no systematic review.
  • Most observed that docs were created by developers with no formal tech writing training.
  • Many noted that docs written by non-native language speakers and would benefit from grammatical review.
But where should we start? We needed to decide on what we wanted, what we should work on first.

What’s the definition of good docs?

And then we realized that we didn’t have a good definition of “good documentation.” For our software projects, we have a comprehensive incubation process to assess the maturity of software and the project’s community, but we couldn’t find a similar set of metrics to define “good documentation.” So we started TheGoodDocsProject, to collate “best-practice templates and writing instructions for documenting open source software.” This helped us define what we were aiming for, and prioritize what we can achieve with our available resources.

Documentation audit

Once we knew what good docs looked like, we were then able to audit the status of project’s docs:
  • What documentation do we have?
  • Does it cover all the functionality?
  • Does it cover end-user needs?
  • Is the documentation any good?
We discovered that the quality, currency, and completeness of our OSGeo docs were immature when compared to the quality software they described.

It takes a village to raise good docs

In researching open source projects’ documentation needs, it’s become clear that crafting good docs requires multiple skillsets. Ideally, a doc team would have access to:
  • A developer with a deep understanding of the software being described.
  • A software user who’s able to explain the application within the context of the application’s domain.
  • An educator who understands the principles of learning.
  • An information architect who understands how to structure material.
  • A writer who writes clearly and concisely with good grammar.
  • A translator who can translate docs into multiple languages.
  • A DevOps person who can set up doc build pipelines.
  • A community builder, facilitator, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas collaborate together.
Technical writers usually have a high-level understanding of most of these domains and their skills are often under-appreciated and under-utilized, especially if directed with a vague “just clean up the grammar and stuff”. The best docs typically have been influenced by multiple stakeholders, which can be partly achieved using templates to collaborate between domains, timeframes, projects and organizations.

Tools for documenting open source projects are painful

We experienced significant difficulties trying to convert between writing and software toolsets. We love the versioning of git, are frustrated by clunky Markdown interfaces, and want access to editing and review workflows of Word and Google docs, along with grammar and syntax plugin tools such as Grammarly. Translation tools such as Transifex are pretty cool, too.

If a project were to address this use case, it would be an awesome gift to the open source community. Having someone write an application which addresses this use case would be helpful. Maybe there is an idea in here for a future Google Summer of Code?

Achievements during OSGeo’s Season of Docs

We’re quite proud of our achievements during OSGeo’s participation in the Season of Docs. Our allocated tech writers have amplified the effectiveness of our existing documentation communities, and our documentation communities have amplified the effectiveness of these tech writers.
  • Felicity Brand worked with around 50 of OSGeo’s open source projects to update their Quickstarts as part of our OSGeoLive distribution of software.
  • Swapnil Ogale worked directly with GeoNetwork’s documentation team, auditing the breadth of docs, and their quality, setting up templates for future docs to work towards, and updating a number of the docs.
Further:
  • We kicked off TheGoodDocsProject—“Best practice templates and writing instructions for documenting open source software.”
  • In conjunction with the OGC and ISO spatial standards communities, we kicked off an OSGeo Lexicon project, to coordinate official definitions for terminology used within the OSGeo context. This will apply best practice definitions to prior haphazard glossaries.
  • We did a deep-dive analysis of the documentation challenges faced by QGIS, one of OSGeo’s most successful projects. Surprisingly, their biggest problem isn’t a lack of tech writers or complicated tools (although they are factors). The key problems center around:
    • Poorly capturing community goodwill and offers of assistance.
    • A lack of direction.
    • Struggling to keep up with a rapidly evolving software baseline.
    • Insufficient writing expertise.
    • A high technical barrier to entry.
    • Documentation and training being generated outside of the core project.
    • Awkward documentation tools and processes.

Season of Docs 2020

Does tech writing interest you? If so, check the Season of Docs projects for 2020 and consider taking part.

By Cameron Shorter, Google technical writer and geospatial open source developer

Season of Docs announces participating organizations for 2020

Season of Docs has announced the 50 participating open source organizations! You can view the list of participating organizations on the website.

During the technical writer exploration phase, which runs from now until June 8, 2020, interested applicants explore the list of participating organizations and their project ideas. They should reach out to the organizations to gain a better understanding of the organizations and discuss project ideas before applying to Season of Docs. Technical writer applications open on June 9, 2020 at 18:00 UTC. 

For more information about the technical writer exploration phase, visit the technical writer guide on the website.

What is Season of Docs?

Documentation is essential for the adoption of open source projects as well as to the success of their communities. Season of Docs brings together technical writers and open source projects to foster collaboration and improve documentation in the open source space. You can find out more about the program on the introduction page of the website.

During the program, technical writers spend a few months working closely with an open source community. They bring their technical writing expertise to the project's documentation and, at the same time, learn about the open source project and new technologies.

The open source projects work with the technical writers to improve the project's documentation and processes. Together, they may choose to build a new documentation set, redesign the existing docs, or improve and document the project's contribution procedures and onboarding experience.

How do I take part in Season of Docs as a technical writer?

First, take a look at the technical writer guide on the website. The guide includes information on eligibility and the application process.

Then participate in the technical writer exploration phase, create a technical writing application and prepare your application materials. On June 9, 2020 at 18:00 UTC, Season of Docs will begin accepting technical writer applications and publish a link to the application form on the website. The deadline for technical writer applications is July 9, 2020 at 18:00 UTC.

Is there a stipend for participating technical writers?

Yes. There is an optional stipend that technical writers can request as part of their application. The stipend amount is calculated based on the technical writer's home location. See the technical writer stipends page for more information.

If you have any questions about the program, please email us at [email protected].

General timeline

May 11 – June 8Technical writers explore the list of participating organizations and project ideas
June 9 – July 9Technical writers submit their proposals to Season of Docs
August 16Google announces the accepted technical writer projects
August 17 – September 13Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors
September 14 – December 5Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period
January 6, 2021Google publishes the list of successfully-completed projects
See the full timeline for details, including the provision for projects that run longer than three months.

Care to join us?

Explore the Season of Docs website at g.co/seasonofdocs to learn more about participating in the program. Use our logo and other promotional resources to spread the word. Examine the timeline, check out the FAQ, and apply now!

By Kassandra Dhillon and Erin McKean, Google Open Source

A Season of Docs story

Lack of clear and reliable documentation is one of the main shortcomings of many open source projects. Last year, Google set out to help change that by announcing the first ever Season of Docs

Season of Docs is an initiative that brings together technical writers and open source projects to collaborate for a few months, benefitting both the communities and writers.

This is the story of Audrey Tavares, one of the writers who signed up for Season of Docs.

Turning incipient curiosity into an opportunity

In 2019, Audrey was completing the Technical and Professional Communication program at Glendon College, exploring technical writing out of curiosity. One of Google’s technical writers, Nicola Yap, completed the same program and visited Audrey’s class in March to talk about her career. It was an enlightening experience, showing technical writing as an attractive alternative with plenty of opportunities, and introducing Audrey to Season of Docs.

For Audrey, this experience meant stepping into unknown territory—she knew nothing about open source software. Naturally, the first step was to familiarize herself with the communities and understand the software development paradigm. After spending time learning she submitted her Technical Writer application—which was accepted—and was assigned to Oppia, an online educational platform.

Main challenges

Audrey had two mentors to help her on her journey: one in India and the other in the United States. As you can imagine, this revealed the first challenge—time zones. While the first few days were stressful, as navigating schedules across time zones was a daunting task,with a little work, they soon came up with an arrangement that worked for everyone.

The second challenge was learning the tools. For most of us, writing a document involves opening a word processor and typing some text, however, Audrey was about to find out, things are a bit more intricate when it comes to documenting code.

When presented with the choice of a documentation tool set, Audrey decided on Write the Docs. It seemed like a very popular tool among open source communities. How hard can it be to use, right? Well, it’s not so much about how difficult it is, but how different it is for someone unfamiliar with a common software development workflow since it entails learning a few things:
Audrey was not dismayed. She pushed forward and gradually learned these new tools. Both mentors were always available, willing to help, and answered all of her questions. Their mentorship was key to her success.

Every end is a new beginning

After Season of Docs was over, Audrey decided to remain part of the Oppia community to actively contribute to make the platform even better.

The experience allowed Audrey to walk away from Season of Docs with a new set of technical skills, communication skills with software engineers, an extended professional network, and a new item in her résumé. She now works as a technical writer for a software company in Toronto.

Applications for Season of Docs 2020 start on April 13 for open source organizations and on May 11 for technical writers. Check the official announcement to learn how to participate.

By Geri Ochoa, Google Cloud

Announcing Season of Docs 2020

Google Open Source is delighted to announce Season of Docs 2020!

Season of Docs brings technical writers and open source projects together for a few months to work on open source documentation. 2019 was the first year of Season of Docs, bringing together open source organizations and technical writers to create 44 successful documentation projects!

Docs are key to open source success

Survey after survey show the importance of good documentation in how developers choose and use open source:
  • 72% of surveyed developers say “Established policies and documentation” is a key decision factor when choosing open source
  • 93% of surveyed developers say “Incomplete or outdated documentation is a pervasive problem” in open source
  • “Lack of documentation” was the top reason developers gave for deciding against using an open source project
Open source communities know this, and still struggle to produce good documentation. Why? Because creating documentation is hard. But...

There are people who know how to do docs well. Technical writers know how to structure a documentation site so that people can find and understand the content. They know how to write docs that fit the needs of their audience. Technical writers can also help optimize a community’s processes for open source contribution and onboarding new contributors.

Season of Docs brings open source projects and technical writers together with the shared goal of creating great documentation. The writers bring their expertise to the projects, and the project mentors help the technical writers learn more about open source and new technologies. Communities gain new docs contributors and technical writers gain valuable open source skills.

Together the technical writers and mentors build a new doc set, improve the structure of the existing docs, develop a much-needed tutorial, or improve contribution processes and guides. See more ideas for technical writing projects.

By working together in Season of Docs we raise awareness of open source, docs, and technical writing.

How does it work?

April 13 – May 4Open source organizations apply to take part in Season of Docs
May 11Google publishes the list of accepted mentoring organizations, along with their ideas for documentation projects
May 11 – July 9Technical writers choose the project they’d like to work on and submit their proposals to Season of Docs
August 10Google announces the accepted technical writer projects
August 11 – September 11Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors
September 11 – December 6Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period
January 7, 2021Google publishes the list of successfully-completed projects.
See the timeline for details, including the provision for projects that run longer than three months.

Join us

Explore the Season of Docs website at g.co/seasonofdocs to learn more about participating in the program. Use our logo and other promotional resources to spread the word. Check out the timeline and FAQ, and get ready to apply!

By Erin McKean, Google Open Source

Season of Docs announces the successful 2019 long-running projects


Season of Docs is happy to announce that all eight of the 2019 long-running documentation projects have finished successfully!

The successful long-running documentation projects are (in alphabetical order):

Apache Cassandra (Project Report, Project Description)

CERN-HSF (Project Report, Project Description)

Kolibri (Project Report, Project Description)

Mattermost (Project Report, Project Description)

MDAnalysis (Project Report, Project Description)

Open Food Facts (Project Report, Project Description)

Open Source Geospatial Foundation (Project Report, Project Description)

Tor Project (Project Report, Project Description)

Congratulations to the technical writers and organization mentors on these successful projects!

During the program, technical writers spent a few months working closely with an open source community. They brought their technical writing expertise to improve the project's documentation while the open source projects provided mentors to introduce the technical writers to open source tools, workflows, and the project's technology.

The technical writers and their mentors did a fantastic job with the inaugural year of Season of Docs! Participants in the 2019 program represented countries across all continents except for Antarctica!

You can view a list of the 44 successfully completed technical writing projects and read their project reports on the Season of Docs website.

What’s next?

Program participants should expect an email in the next few weeks about how to get their Season of Docs 2019 t-shirt (sure to be a collector’s item)!

If you’re interested in participating in a future Season of Docs, stay tuned for more information shortly—watch for posts on this blog and sign up for the announcements email list.

By Erin McKean and Kassandra Dhillon, Google Open Source

Season of Docs announces the successful 2019 long-running projects


Season of Docs is happy to announce that all eight of the 2019 long-running documentation projects have finished successfully!

The successful long-running documentation projects are (in alphabetical order):

Apache Cassandra (Project Report, Project Description)

CERN-HSF (Project Report, Project Description)

Kolibri (Project Report, Project Description)

Mattermost (Project Report, Project Description)

MDAnalysis (Project Report, Project Description)

Open Food Facts (Project Report, Project Description)

Open Source Geospatial Foundation (Project Report, Project Description)

Tor Project (Project Report, Project Description)

Congratulations to the technical writers and organization mentors on these successful projects!

During the program, technical writers spent a few months working closely with an open source community. They brought their technical writing expertise to improve the project's documentation while the open source projects provided mentors to introduce the technical writers to open source tools, workflows, and the project's technology.

The technical writers and their mentors did a fantastic job with the inaugural year of Season of Docs! Participants in the 2019 program represented countries across all continents except for Antarctica!

You can view a list of the 44 successfully completed technical writing projects and read their project reports on the Season of Docs website.

What’s next?

Program participants should expect an email in the next few weeks about how to get their Season of Docs 2019 t-shirt (sure to be a collector’s item)!

If you’re interested in participating in a future Season of Docs, stay tuned for more information shortly—watch for posts on this blog and sign up for the announcements email list.

By Erin McKean and Kassandra Dhillon, Google Open Source

Season of Docs Announces Results of 2019 Program

Season of Docs has announced the 2019 program results for standard-length projects. You can view a list of successfully completed technical writing projects on the website along with their final project reports.

During the program, technical writers spent a few months working closely with an open source community. They brought their technical writing expertise to improve the project's documentation while the open source projects provided mentors to introduce the technical writers to open source tools, workflows, and the project's technology.

The technical writers and their mentors did a fantastic job with the inaugural year of Season of Docs! Participants represented countries across all continents except for Antarctica! 36 technical writers out of 41 successfully completed their standard-length technical writing projects, and there are eight long-running projects in progress that are expected to finish in February.

  • 91.7% of the mentors had a positive experience and want to mentor again in future Season of Docs cycles
  • 88% of the technical writers had a positive experience
  • 96% plan to continue contributing to open source projects
  • 100% of the technical writers said that Season of Docs helped improved their knowledge of code and/or open source

Technical writing projects ranged from beginners' guides and tutorials to API and reference documentation; all of which benefited a diverse set of open source projects that included programming languages, software, compiler infrastructure, operating systems, software libraries, hardware, science, healthcare, and more. Take a look at the list of successful projects to see the wide range of subjects covered!

What is next?

The long-running projects are still in progress and finish in February 2020. Technical writers participating in these long-running projects submit their project reports by Feb. 25, and the writer and mentor evaluations are due by Feb. 28. Successfully completed long-running technical writing projects are then published on the results page on March 6, 2020.

If you were excited about participating, please do write social media posts. See the promotion and press page for images and other promotional materials you can include, and be sure to use the tag #SeasonOfDocs when promoting your ideas on social media. To include the tech writing and open source communities, add #WriteTheDocs, #techcomm, #TechnicalWriting, and #OpenSource to your posts.

Stay tuned for information about Season of Docs 2020—watch for posts in this blog and sign up for the announcements email list.

By Andrew Chen, Google Open Source and Sarah Maddox, Cloud Docs

Season of Docs Announces Technical Writing Projects

Season of Docs has announced the technical writers participating in the program and their technical writing projects! You can view a list of organizations and technical writing projects on the website.

The program received nearly 450 technical writer applications, and with them, over 700 technical writing project proposals. The enthusiasm from the technical writing and open source communities has been amazing!

What is next?

During the community bonding period from August 7 to September 1, mentors must work with the technical writers to prepare them for the doc development phase. By the end of community bonding, the technical writer should be familiar with the open source project and community, understand of the product as a whole, establish communication channels with the mentoring organization, and set clear goals and expectations for the project. These are critical to the successful completion of the technical writing project.

Documentation development begins on September 2, 2019.

What is Season of Docs?

Documentation is essential to the adoption of open source projects as well as to the success of their communities. Season of Docs brings together technical writers and open source projects to foster collaboration and improve documentation in the open source space. You can find out more about the program on the introduction page of the website.

During the program, technical writers spend a few months working closely with an open source community. They bring their technical writing expertise to the project's documentation and, at the same time, learn about the open source project and new technologies.

The open source projects work with the technical writers to improve the project's documentation and processes. Together, they may choose to build a new documentation set, redesign the existing docs, or improve and document the project's contribution procedures and onboarding experience.

General Timeline

August 6Google announces the accepted technical writer projects
August 7 - September 1Community bonding: Technical writers get to know mentors and the open source community, and refine their projects in collaboration with their mentors
September 2 - November 29Technical writers work with open source mentors on the accepted projects, and submit their work at the end of the period.
December 10Google publishes the list of successfully-completed projects.

See the full timeline for details, including the provision for projects that run longer than three months.

Find out more

Explore the Season of Docs website at g.co/seasonofdocs to learn more about the program. Use our logo and other promotional resources to spread the word. Check out the FAQ for further questions!

By Andrew Chen, Google Open Source and Sarah Maddox, Google Technical Writer