Skip to main content

Contributing to Documentation

What to change and Why​

Documentation is fast-moving and ever-changing. Please think carefully about what you're changing and why; what will it contribute going forward? Extensive rewrites and new pages should be considered very carefully and coordinated in our documentation Matrix room.

Please Self-Review​

Before finalizing your changes, please be courteous to reviewers and run your changes through, at least, a spellchecker (e.g. apsell) and potentially a grammar checker. AI is fine for this though please use it sparingly for generating content. Make sure you re-read what comes out and adjust as required. We appreciate individual writing styles but the bulk of our review back-and-forth is over minor issues like this, so please do your part to get it right first.

Peer Copyediting​

For very large changes, we encourage the idea of peer copyediting. Instead of submitting a massive PR and then having back-and-forth line-by-line editing in there, we suggest placing your new/updated doc in a collaborative document editor such as Framapad and sharing it in our documentation Matrix room. You can then, between chat and the collaborative editor, obtain a line-by-line copyedit for spelling, grammar, and formatting, without back-and-forth in the PR. Once both sides are happy with the changes, a pull request can then be submitted.

While this does seem like "more work", for substantial changes this should ideally be a small part of the entire process, and will help ensure that final reviews go more smoothly.

Peer Reviews​

Due to the volume of pull requests to our documentation repo and the varying sizes of them, some pull requests will take a long time to review, and potentially languish as a result.

Before (or, immediately after) submitting a PR for review, we ask you to find another PR from another person, ideally one which is not already peer- or team-reviewed, and perform a thorough readthrough of the changes. Make sure they make sense to you, that the copyediting is good, and provide a GitHub review of it. If necessary please point out any change suggestions. This will help go a long way to helping your PR be reviewed, as the next contributor can review your PR in turn.

Blog Posts​

Blog posts are exclusively written by our team members; we do not accept outside blog posts under any circumstances. Blog posts should follow all the above processes, and further require final approval from the Core team in addition to regular documentation approvers. Blog posts may stay in draft or review status for some time, until the event they correlate with (e.g. a release); the date should always reflect the final (expected) publishing date.