Improving Rails documentation is one of the core pillars of why the Rails Foundation was formed, so we are pleased to share an update on how that mission is progressing.

Thanks to organic contributions from the community over the past 20 years, the Rails documentation is already in a fantastic place - arguably one of the most in-depth and robust set of docs in tech.

Our mission at the foundation is to assemble a team to go over this impressive body of work with a fine-tooth comb. We want to fill in any gaps, check that the content is still up-to-date, and make sure that the writing is consistent, clear, and accessible for developers of all levels - from the experienced Rails dev to the new developer learning Rails (or web development) for the first time.

The team is assembled and the work just began, so here is how we work, what’s next, and how you can help.

The team

• Carlos Antonio da Silva
• Ridhwana Khan
• Bhumi Shah

The process

• Step 1: Audit We are conducting an exhaustive audit of the entire Rails documentation site as well as the open issues labeled with ‘docs’ in the Rails repo, noting down what is missing or what can be improved upon in each guide.
• Step 2: Writing & team review When a section or guide has been audited, it is assigned to a writer for reviewing/editing/writing. As a team, the writers also review each other’s work so that each guide or section has been seen by at least two pairs of eyes before the next step.
• Step 3: PR & community review Once a piece of documentation has been polished and is ready for community input, we will create a PR in the Rails repo on GitHub, marking it with RF-DOCS in the title and the ‘rails foundation’ label. These PRs will stay open for one week, after which the writers will process any feedback and we will merge the PR.

The last step is where you, the Rails community, come in.

How to help

If you’re interested in helping improve the documentation, keep an eye out for the PRs named RF-DOCS and labeled ‘rails foundation’. If you have experience with a certain component or feature, we would love if you reviewed and commented on that PR from a technical perspective.

Furthermore, if you come across a section of a guide that needs work, feel free to open an issue in the Rails repo and label it with ‘docs’. We’ll continue monitoring these issues and the team will step in where needed.

‘I occasionally contribute PRs for documentation. Should I stop?’ ‘I have an open PR about a doc update. Should I close it?’

Absolutely not. The Rails documentation is the amazing resource that it is today thanks to such community contributions, so this project is meant to work alongside that - not interrupt it. Please continue contributing.

Things could change

We reserve the right to change this way of working if it becomes unwieldy or if it hampers the work that the Rails Core, Committers, and Issues team are focused on.

If you have any questions or feedback about any of the above, feel free to reach out to foundation@rubyonrails.org.

And stay tuned: we will more share updates soon about upcoming tutorials and the UX design of the guides, too.