Selecting a technical writer

Current phase:
Preparing for announcement of results. See timeline.

This page contains tips for open source organizations on how to assess and select the right technical writer for their Season of Docs project proposal.

Introduction

Open Source Organizations must hire a technical writer to work on their proposed project. Organizations must source their own technical writer. Technical writers interested in working with organizations participating in Season of Docs may be found in the Season of Docs GitHub repo, and in the #season-of-docs channel in the Write the Docs Slack.

Assessing a technical writer

It is recommended that you request examples of previously developed documentation from the technical writers you are considering, so that you can focus on evaluating their technical writing skills and experience.

Technical writing skills and experience

  • Examine the technical writer's prior experience. Ideally, the technical writer should have some prior experience in writing technical documentation for the software industry. One of the goals for Season of Docs is to give technical writers the opportunity to get involved with developer-focused products. For that reason, it's not essential that the writer has experience with APIs or SDKs or other developer platforms, even if your project focuses on a developer audience.

  • Focus on language and communication skills. Evaluate the technical writer's previous work from this point of view. Most importantly: Can you understand what the person wrote? If you want to do an indepth review of the language of the technical writer's work, look for consistency in punctuation and phrasing, correct spelling, and clear language. Is the phrasing simple or complicated? Are the sentences short or do they run on until they become difficult to follow?

  • Pay attention to doc design and layout. Check the overall layout of the document sample(s). Is the design logical? Can you easily find your way around the document or documentation set? Is there duplication of content or are there obvious gaps?