How to Contribute to BigCommerce Dev Docs

As BigCommerce continues to grow, we strive to improve the overall experience of our developers wherever we can. By continually creating ways to hear your comments and suggestions better, we can ensure that your experience with BigCommerce only gets better. That is why our team is excited to announce that you can now contribute to our developer documentation!

As the BigCommerce Community continues to mature, we want to create opportunities for you — our fellow developers — to enhance our community using your product expertise or eagle eye for making documentation better. This way, we can continue to build a community where developers have the freedom to contribute to BigCommerce and their overall experience.

Evolution of Our Documentation

We’ve been consistently working on our documentation to make sure that we’re creating an experience that’s as easy to navigate as possible for you.

In late 2016, our focus on creating user-friendly documentation left room for improvement. At the time, we were using completely different tools to publish and manage our docs. We had two sets of resources: API reference docs and Stencil Theme docs. These two documentation sets lived under entirely separate domains, leading to a disconnect in look, feel, and tone. The two sections were managed by different teams, further increasing the disconnect between the two sets of resources.

In addition to a lack of a changelog, our API reference docs lacked language-specific examples. Most of our challenges tied back to our over-reliance on automating the documentation process. This over-automation ended up making our documents harder to manage and less user-friendly.

In 2017, our team focused on enhancing the quality of our API reference documentation. This led to us going through multiple changes, including embedding a new tool into our documentation to better facilitate the creation of language-specific examples. Adding this functionality to our docs made our API reference information much more consumable, but caused significant slowdowns to our site. Unsatisfied with the trade-off, but closer to our goal of improving our documentation, our team continued to enhance the documentation experience.

In 2018, we sought to refine our documentation plan further. A large part of our strategy focused on relocating our dev docs from a central, locked-off CMS to the open, accessible platform on GitHub. While exploring possible platforms, we settled on Stoplight. Satisfied with the extensive functionality and possible time-saving features of the platform, we decided that now was a good time to create the developer center that we had imagined for some time now. We united our API reference documents and Stencil Theme docs under one united domain along with a weekly-updated changelog, a feedback feature, and this developer blog. Not only did the site run much faster and smoother, but it also led to a more consistent experience overall. We had created a space specifically for our community developers to locate the information that would allow them to build what they needed to enhance their e-commerce goals.

As a result of that change, we were able to achieve two main objectives: separation of concerns and access for outside contributors. Both of these allowances provide a better experience for our audience.

Separate concerns.

Before the recent restructuring of our developer documentation, our content directly connects to our specific CMS platform of choice. As such, we were limited in when and how we could make changes to our docs. While this wasn’t a problem when our team was smaller, it was starting to become more of a bottleneck in our ever-evolving process. By migrating to GitHub and separating our pages into individual Markdown files, we freed our content from our CMS system. That allowed our team members to edit content simultaneously, update our content in our preferred text editors, and open our GitHub repository to external contributions.

Allow for contributions.

As a result of our team separating our dev docs content from our CMS and making the Markdown files accessible on GitHub, we also made it possible for members of the BigCommerce community to contribute to our documentation repository. Facilitating contributions was one of the reasons we restructured how we handled our documentation on our end. Nothing is more important to us than fostering active and open lines of communication with members of our community. Allowing contributions to our development documentation repository is one way to address your concerns and suggestions directly. By accepting pull requests and issues from our community, we can better tailor our documentation to your needs.

Why Allow Contributions?

Our team believes that part of creating a conducive developer experience includes allowing input from the developers within the BigCommerce community. As members of this community, you are frequently interacting with our documentation to achieve your e-commerce goals. Allowing you to easily suggest (or even make!) changes to the dev docs improves the overall helpfulness of those resources.

Open community.

Is an API specification document out of date? Is an endpoint not returning what you thought it would? Did you notice a small (but annoying) typo? That’s where contribution comes into play. Make a quick pull request to address the mistake, or create an issue in our repository so our team can fix it.

Easy accessibility.

What better place to encourage community contributions than GitHub? By making our documentation repository available to our entire community, we wanted to promote fast and precise suggestions about our documentation. We also wanted to make sure that we fit into your established workflow. Since most developers are more than familiar with GitHub, we decided to add this path to our growing inroads to facilitate community.

More visibility.

What are other members of the BigCommerce Community encountering when they interact with our developer docs? Now that our documentation is open to contributions on GitHub, everyone can get a sense of the most recent updates to our documentation as a result of you, our diligent contributors. Also, if there are multiple comments or requests for additional resources about a particular aspect of our documentation, our team can build it out to further enhance your experience.

Now It’s Your Turn

Ready to contribute? Head to the BigCommerce DevDocs repository on GitHub. Feel free to submit a pull request or issue, depending on the type of situation. Be sure to read through the contribution guide before creating your first pull request.

You can also access the repository directly from our documentation! Click the “Contribute to Docs” button at the upper-right corner of any of our documentation pages. That will take you directly to the repository’s contribution guide.

We’re looking forward to seeing your suggestions and requests from this new way to connect with the BigCommerce community. Remember, we welcome all pull requests, big or small. Don’t hesitate, contribute!