Documentation is undergoing some changes for the better at Couchbase. Matt Carabine and the documentation team have been working to improve the build process, backporting, and review. And, they have made it easier to contribute to documentation in the process.

Contributing to the documentation

Couchbase documentation is open source, but until recently, there were a number of problems. If you were looking to make a substantial change or maybe just fix a quick typo, you were faced with one or more of these questions:

Where do I look to make a change?

What file do I change?

What file maps to the doc page I’m looking at?

How do I change it?

It was not always clear how to go from a documentation URL to a specific file in the Github repository.

Now, that’s changed. If you visit a page in the documentation, you will notice an "Edit on GitHub" link on each page. Click this link and you’ll be taken to GitHub to edit the file directly (your first time, you will be prompted to create a fork).

It astounds me that we had such great contributions from so many people so quickly! Thank you, everyone, for helping to make the documentation better.

How did we get here?

To make contribution easier, the build process had to be improved. Previously, it involved a bunch of manual steps: pull source, build locally, zip up the results, FTP them to a server, run one or more slow build server tasks manually. Now you’ll see that the build step happens much more quickly in the pull request, and previews are generated quickly.

The reviewing of content was also improved. Previously, previews were only possible on a single location. There was no simultaneous reviewing possible. This, combined with the slow, manual builds, was frustrating, and made it difficult to review all changes, let alone external ones.

Finally, backporting to other versions of Couchbase Server documentation was also a problem. The documentation is stored in separate branches for each version, so if an issue is raised and fixed in 4.6, it may also apply to 4.5, and so on. That’s a very manual process, but a @cb-docs-robot was created to automate the backporting (which you’ll see in many of the above examples).

How are we doing?

Another thing we’ve added is the ability to give us feedback on the documentation right from your browser.

Simply find the "Feedback On This Page" button at the bottom right of your browser, click it, and write feedback.

Summary

These documentation improvements help us both internally and externally. We hope that it will make your experience with the documentation less frustrating and more enjoyable. We welcome your feedback! Please check out the Couchbase docs on GitHub.