Documentation proofreading and review#

Historically the Openverse project has occasionally done a “documentation bug bash” where maintainers sat down together to read through our existing documentation and identify potential issues or necessary changes. While this should happen in a concerted, maintainer-wide effort at least once a year, we can also individually perform some aspect of this on an ongoing basis.

What to look for#

When proofreading a particular documentation page, consider the following:

  • Who is the audience? Is the document accessible to that audience in tone, language, and location?

  • What is the purpose? Is the document’s purpose clear and does the document fulfill that purpose?

  • What is the scope? Does the document sufficiently cover its intended scope? Are there aspects missing? Are there spurious aspects that could be broken into separate documents? On the other hand, are there pages that should be combined or more clearly linked, whether in text or via organisation, in order to fully cover the intended scope?

  • Does it work[1]? If the document is a guide, try out the steps for yourself and confirm that they work. Are there gaps in the steps that can be explicitly documented? Can any steps be simplified? Is there spurious information that could be moved into supplementary documentation, especially information that unnecessarily complicates the guide?

If you identify discrepancies in any of these areas, open an issue. If possible, suggest an edit that would fix or improve the situation.

Additionally, we should look for opportunities to document currently undocumented parts of the project. If you notice these, open issues to request the documentation.