Current phase:
The 2020 Season of Docs program finished on March 15, 2021. See
timeline.
This page contains guidelines for technical writers on how to create your project report when you've finished your work for this year's Season of Docs.
Submitting your project report
When project finalization phase opens, you will be able to submit your project report by completing a form that becomes available in the project finalization section of the technical writer guide.
Information to include in the project report
This section describes the type of information you can supply in your project report. The project report form will include free-text fields as well as multiple-choice questions.
Link to your work
Provide a link pointing to a description of the work you've done.
The link should point to a document that contains a short description of the work done, the documentation that the open source project merged into its repository, a summary of the current state of the project, and a list of challenges and learnings.
The link will appear in the Season of Docs results published on the website. The published results demonstrate the work that you've completed during the program. The published results are also a great way for you to refer back to your work as part of your resume.
You should share your link with your mentor and ask for a review before submitting your project report.
Requirements for your project report
Take the following requirements into account:
- The linked content must make it easy to identify the work that you completed during Season of Docs, that is, the changes that you made or the new documentation that you wrote.
- The work should be in a stable location. You can't change the URL after submission.
Someone else should be able to use the content at (or referenced from) the target of the link to build upon your work.
- If your work is 100% complete, other people should be able to use it.
- If your work is not 100% complete, it should be clear what's left to do.
Good examples of how to describe your work
You don't have to do all (or any) of these things, but these are some ways you can satisfy the requirements:
Create a blog post or web page or public GitHub gist that describes the work you've done and links to the commits you've made and the repositories you've worked on. If there is still work to be done on the project, include a description of that work. You can also share highlights or challenging pieces.
This is the best option because it allows you to easily include a lot of information. This is good because it clearly shows the work you did, and makes it easy for others to use and understand your contribution.
If using GitHub, and all of your work is covered by a single pull request, you can use that link.
- Ensure that the pull request description is detailed.
- Make sure the description clearly notes that the work is for Season of Docs.
- If the pull request needs more work after Season of Docs is over, make sure the last Season of Docs commit notes this fact.
- This method of providing a project report has the benefit of having the change log, a list of commits, and the review comments all in one place.
If your GitHub repository is single purpose for Season of Docs, add a README file containing the details of your work.
Create a public folder in Google Drive and include all of the patches you've created.
Create a public spreadsheet with Google Sheets and list all your commits.
Link to a single issue in a public issue tracker, that contains clear references to your work and anything else appropriate. The issue should track all the work you've done. Make sure the issue lists all the commits or that it's easy to find the commits in another way.
Link to a unified or context diff of your changes. Be sure to include a header that includes the name of your technical writing project and who you are, so it's useful to others.
Bad examples of how to describe your work
Don't do these things:
- Link to a tarball or zip file containing the entire project's source code or your working directory.
- Link to the top of the project's primary source repository. For example, if you're working on cpython, this link is not useful: https://github.com/python/cpython.
- Link to your clone of the project's source repository. This makes it hard to see what your changes are because your work is mixed with other people's work.
- Link to your project description on the Season of Docs website.
For the mentors
Please help your technical writer create a proper project report. It's important to do this before you create your own evaluation of the technical writer's work.
Check the following:
- The submission must meet the requirements described above.
- The submission must include a description of the work done, the requirements satisfied, and the reasons for any specific decisions made.
The idea of Season of Docs isn't that technical writers churn out a lot of documentation. It's important that the work be potentially useful to the hosting open source project.