Doc development. See timeline.
This page contains some questions to consider when creating an agreement with a technical writer for Season of Docs. This is not intended to be legal advice or an exhaustive list of all possible points to consider when creating technical writing agreements for open source projects. Depending on your organization or project’s needs, you may wish to consult your own legal counsel before onboarding a technical writer.
Scope of work
- Create a list of the work covered by your agreement. Be as specific as possible. For example, instead of “API Documentation” make a list of what endpoints need to be documented, and what information must be included, such as a sample curl command or a list of parameters.
- How will you know if a piece of content is ‘finished’?
- Other things to consider:
- Who will own the copyright to the work? What license will it be released under (these are different!)? What credit will the technical writer receive (mention on site, listed as contributor, etc.)? What if the content needs to be relicensed in future? For example, if you expect the technical writer to sign your open source project’s Contributor License Agreement, you should communicate that.
- If you expect the technical writer to participate in multiple revision passes, spell those out. For example, you may state that you expect a first draft, then a second pass to address technical issues, then a final pass for proofreading.
- If you expect the technical writer to deliver content in a specific format, such as Markdown, include this in your agreement.
- Agree with the technical writer on a payment schedule tied to firm dates and deliverables.
- Will you pay an up-front amount at the beginning of the work?
- What happens if the work cannot be used or accepted (because the project’s priorities have changed or because a reviewer dropped out, etc.)? Can you pay a ‘kill fee’ to help compensate for the time spent by the technical writer?
- Who will be responsible for any currency conversion fees related to the method of payment chosen?
- Do you expect the technical writer to be available for video calls or meetings?
- What channels of communication will you use and what are the expected response times? For example, if you expect a technical writer to respond to emails (or messages in Slack) within a day, make that explicit.
- Who from the project can the technical writer contact for different questions, such as payment problems, need for review, unblocking problems with tools or channels, etc.
- Is there a specific process the writer should use for submitting their work, obtaining feedback or reviews, etc.?
- What tools (or versions of tools) does the technical writer need to use to create their work?
- Who is responsible for helping the technical writer get set up, get access, or get permissions?
- How will you resolve disagreements about the quality of the technical writer’s work? Who has the final say?
- What would the process be for releasing the technical writer from the project? For example, missing three deadlines in a row, or turning in work of unacceptable quality. When enforcing the process, consider giving explicit next steps (“We expect a pull request for the first draft to be submitted by next Friday” rather than “Please submit your work as soon as possible.”)
- If a technical writer needs to drop out, how should they communicate that? If possible, should they give notice, create a handoff doc or have a handoff call?
- Don’t forget to consider the obligations of the project to the technical writer. For example, if your project mentors drop out and cannot be replaced, or if promised reviews cannot be completed, consider paying a portion of the remaining funds to the technical writer even if the project cannot be completed, to compensate the writer for their time.
- State explicitly that the technical writer is bound by the project’s Code of Conduct, and link to your Code of Conduct enforcement process. You may wish to make explicit that CoC violations will result in termination of the project and forfeiture of payment for any outstanding work.