Workflow: Collaborative Documentation with Suggested Edits

Recently, we released a brand new version of our Suggested Edits feature and as we were testing it internally, it dramatically changed how we approached writing documentation. It’s allowed us to more easily collaborate on documentation and merge updates exactly when features go live.

For all major changes to documentation (whether it be new features, major changes to existing features, or even just improving an existing page) all of the edits occur in suggested edits. After a suggested edit is created, the original creator can keep making changes. It’s no longer necessary to get it finished and perfect on the first try—which means that as a feature is being developed, the documentation can be writing incrementally over time.

Once the documentation is ready for review, an admin can take a look and leave comments on anything they notice, and even make changes themselves! Documentation is best when it is a collaborate process. We encourage multiple people to take a look and provide feedback to make sure that it’s the best that it can be. After this process is completed and the feature/change is ready to go live, we merge the suggested edit!

This workflow works great at our small size, and it scales really well to large teams where not everyone needs admin access. Most members of the team can just make changes through suggested edits, since most users don’t need any of the functionality or control that full admin access provides.

These changes have made a huge improvement to how we write documentation and we can’t wait for everyone to try them out!