How to contribute to documentation as a new user
Contributing to a project is often a daunting challenge. Each project has an idiosyncratic way of organizing folders, accepting contributions, writing examples, etc. Fortunately, documentation is a great way to get started. You can usually make noticeable improvements to a package without knowing the full details of the project’s API, and there are always improvements to be made in documentation.
However, it can be hard to figure out how to contribute to a project’s documentation. As a part of the Docathon, there are several projects in need of some documentation help. Here are some ways that you can help out.
- Review tutorials, examples, and written documentation. Ideally keeping a critical eye open for opportunities to improve the materials. This is an excellent opportunity to learn a bit more about your favorite library and propose improvements, fix typos, write a new paragraph, or improve one!
- Look for issues that are labeled as documentation. Many projects have a list of issues related to documentation. Check out if there are any issues labeled Documentation and new-contributor-friendly, e.g.: https://github.com/matplotlib/matplotlib/issues?q=is%3Aopen+label%3ADocumentation+label%3Anew-contributor-friendly. If you can’t find any, you can always open an issue to offer your services as a documenter!
- Improve API/function documentation. API documentation should clearly explain the usage and meaning of all inputs and outputs for functions, objects, etc. This is extremely important for ensuring that the package is easy to use. However, many packages fall short of this goal. Ensuring that the documentation fits a common format (such as numpydoc for Python projects) makes this job a lot easier. If the documentation isn’t already in a common format then submit an issue suggesting converting the documentation, or make this format switch yourself for a few functions in a pull-request. If there is already a clear formatting preference in the package, then perhaps you can improve under-documented functions or make existing documentation clearer.
- Contribute new examples. Look through the examples provided in a project’s documentation and see if there are any glaring omissions. Is there some function that you use that isn’t covered in the examples? If so, you could create a short script that shows off the functionality. If you see two examples showcasing the same feature, try merging them!
- Improve the language of examples. Many examples / tutorials / vignettes are thrown together relatively quickly and are often written in an unclear and overly complex way. Check the comments and narrative sections of the documents and think about how they could be improved. If you see ways to improve the language, open an issue or submit a pull request with your suggested changes.
- If there are contribution guidelines, adhere to them as much as possible. This will reduce the amount of time needed to get your contribution merged into the main codebase. Either way, try to style any new contributions so that they’re similar to what is already there.
We hope this helps you get started!