Working with a technical writer

Current phase:
The 2019 Season of Docs program finished on March 6, 2020. See timeline.

Here are some guidelines for open source organizations on how to work with a technical writer that you're mentoring for Season of Docs:

  • Introduce the technical writer to the world of open source and to your community.
  • Help the technical writer use the tools and processes involved in contributing to your project.
  • Explain your product in detail so that the technical writer gains a firm conceptual understanding of the product. This can help the technical writer feel more confident and be more authoritative in their writing for the project.
  • Describe the needs of your audience—that is, the needs of the developers who use your product and/or other groups who use the product.
  • Workshop the important use cases with the technical writer, to help them design the required documentation.
  • Walk through the code when the technical writer needs to understand it before writing the docs.
  • Put the technical writer in touch with the necessary subject matter experts. That is, the developers or other project contributors responsible for the aspects of your product that the documentation will cover.
  • Ensure that the technical writer gets the time and resources they need from the subject matter experts and any other community members.
  • Work with the technical writer to add meaningful code samples to the docs where relevant.

Things to bear in mind

Open source mentors in Season of Docs are not necessarily technical writers. The mentors don't need to have documentation skills. The technical writers bring those skills to the project and to the mentoring relationship.

Instead, the mentors bring their knowledge of their open source community, the product, and the processes and tools that the open source project uses.

An important outcome of the mentoring relationship should be that the technical writer has a rewarding and successful experience in this year’s Season of Docs. A happy experience improves the chances that the technical writer will continue contributing to the open source project after the close of this year’s Season of Docs, and that other technical writers will become enthusiastic about working in open source.