Crowdsourcing Our API Documentation
At Box, we strive to deliver best-in-class API documentation to make it as easy as possible for developers to learn about our APIs.
One of the most important parts of any developer’s journey with a new API is exploring the documentation to understand how the API can be used. Unfortunately, a lot of companies struggle to create and maintain documentation and it is often treated as an afterthought. At Box, we invest a lot of time and resources in our making our documentation as comprehensive as possible, but we don't always have the context and perspective on the job for which a developer is looking to use our APIs. Box helps millions of users collaborate on their content every day using the Box apps and we're bringing that same power to our documentation.
Starting today, developers can suggest changes and additions to the Box API documentation. These changes, similar to a Github pull request, will then be reviewed and approved by the Box Developer Relations team. Once the changes have been approved, they’ll be published to our live documentation. Not only will this improve the documentation, but it will help us better understand what's important to our developer community and prioritize our internal efforts as well.
Check out this video to learn more:
Suggesting edits to our documentation is simple. When you visit docs.box.com, you’ll now see a button to “Suggest Edits” on the right hand side of any guide or reference content. When you click this button, you’ll be prompted to authenticate to our documentation site using your Box account. Once you've authenticated, you're now a contributor to the Box API documentation.
You can modify the existing documentation using the editor or add new elements like code samples or callouts using the buttons on the right side. Once you've completed your edits, simply hit the "Submit Suggest Edits" button on the top-right. You can also add a message explaining your changes. From there, we'll review your changes and, if everything looks good, publish them to our live documentation. We'll be on the lookout for our top contributors and make sure you're recognized for your efforts.
Once you've authenticated using your Box account, you'll be brought to a text editor for that endpoint.
Our documentation is now fully editable, so you can start tweaking and making improvements right away. If you have any questions about this new capability or the Box API documentation in general, you can reach out to us on Twitter (@BoxPlatform) or post a question in the Box Developer Forum.