Current phase:
Results announced
timeline.
Here are some guidelines to help open source organizations work effectively with technical writers.
Introduce the technical writer to the world of open source and to your community
- Give the technical writer a ‘guided tour’ of your community. Where can they ask questions? What regular meetings should they attend, or what mailing lists should they join? What accounts do they need (Github, Discord, Slack)? Make sure they understand your project’s code of conduct, and know how to report any problems. Make sure your technical writer understands the license of your project, and complies with any requirements of other employers around signing CLAs, DCOs, or other agreements.
- If possible, introduce them to a few people in overlapping time zones who can respond quickly to questions about the community or project.
- If you can, send them some project swag!
Help the technical writer use the tools and processes involved in contributing to your project
- If your processes aren’t well-documented, set up a time to walk the technical writer through their first contribution, issue, or pull request. What templates or tags should they use? Who needs to review their contribution, and how and when should they follow up on reviews? If their work includes code samples, how can they be tested? What do they need to know about your CI/CD process or releases?
Help the technical writer understand your project and its users
- Explain your project 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 the people who use the project. Be as specific as you can—not just ‘developers’ but ‘developers creating web sites’ and ‘developers programming industrial robots’.
- 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 project 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.
Ask questions!
- Your community or project may not have worked with technical writers or documentation contributors before. Take advantage of the opportunity to learn while you share what you know! Ask for feedback on your processes and tools—your technical writer will likely have some suggestions for improvement.