With the Drupal Commerce 2.0 release slated for September 20th, we are making an effort to provide excellent documentation so that our implementers and end users can work with Drupal Commerce efficiently. We also want to encourage contribution at all levels, such as documentation. I am happy to announce we have moved from using Sphinx, a Restructured Text documentation tool, to GravCMS. GravCMS is a PHP based flat-file CMS, which uses Markdown.

Why the change?

We found that while Sphinx provided robust features, it also added a high entry barrier for documentation contributors:

• Contributors had to adjust to Restructured Text, which is kind of like Markdown but not completely.
• Working locally involved needing Python to run Sphinx and generate the documentation HTML
• It required a build script.

After community feedback, it became apparent we needed to find a better solution. Documentation is as crucial a contribution as the code. A community member, yaazkal, suggested using GravCMS. After initial review and community feedback, the platform migration began, and is now complete!

The best fit

Initially, the documentation was using GitBook. GitBook allowed us to use Markdown and have structured content. GitBook had a rough time handling 404 errors, and we had general structure errors. We then reviewed Sphinx. Sphinx is the documentation tool that Symfony uses; and, Platform.sh also hosts Symfony's documentation just like our own. It seemed like a great fit because we could control the theming, have the robust markup of Restructured Text and still allow contributions through GitHub's user interface.

GravCMS gives us everything in our requirements.

• It is easy to run locally: use PHP's built in server.
• Easy to contribute: Markdown, automatic menu generation.
• Editing of documentation can be done within GitHub using Markdown (GitHub does not support Restructured Text)
• It's written in PHP! Which means it's even easier to customise

When tied with our Platform.sh hosting this creates a very welcoming contributor experience. With each proposed change, Platform.sh environments are created for each pull request, allowing to live review of each change.

What is next

With an improved platform, it is also time for more changes to our documentation. To provide best in class documentation, we have implemented a new outline for content. The Drupal Commerce documentation is now split into a User Guide and a Developer Guide to match the two audiences who need documentation.

• User guide: This section acts as an end-users guide. This guide is what evaluators and shop managers will read to understand how to use Drupal Commerce. This guide is where digital agencies can send customers and help build documentation for Drupal Commerce implementation.
• Developer guide: This section is for those implementing Drupal Commerce. It allows us to explain dependencies and how they are used. It will show different integration options. The Developer guide will be primarily for audiences who may not have a strict Drupal background. It is assumed for anyone who is using Drupal Commerce for the first time. We will include an "Adapting from 1.x section." This guide is a section that essentially highlights how developer implementations in 1.x would be done in 2.x

Check out our newly updated documentation at https://docs.drupalcommerce.org and feel free to begin contributing!