The IBM Cloud product documentation project invites Bluemix users to collaborate in creating documentation that reflects the wide range of programming language, tools, and infrastructure used with the platform.
IBM Cloud enables users to quickly create, deploy, and manage applications in the cloud, so you don’t have to deal with any underlying infrastructure — including hosting or managing applications. And, you get to develop with the tools and languages of your choice.
Enabling all IBM Cloud users to edit the product documentation, incorporating their experience with their unique programming languages, tools, and infrastructures, makes the content more accurate and up-to-date.
Hosted in GitHub and authored in Markdown, anyone can contribute by simply following the “Edit in GitHub” button on the docs page, forking the project, updating the source directly, and submitting a pull request.
Enabling not only our subject matter experts, but also those using the platform to collaborate with us on the docs, helps to create more accurate technical content and gets users up and running as fast as possible.
Why should I contribute to the IBM Cloud docs?
We need your subject matter expertise to make IBM Cloud better. When you spot incorrect, inconsistent, or missing information, adding that information to the documentation makes the product better for everyone.
Instead of providing feedback and not knowing how or when it will get incorporated, you can update the source directly, iterate with our IBM Cloud writers and developers through comments in Github, and contribute to the content in a meaningful way. Your valued input will have a rapid and direct impact on the quality and accuracy of the IBM Cloud docs.
How did we do it?
We created a Markdown transform that honors a small set of custom IBM Cloud attributes, allows us to control IDs for translation and the addition of copyrights and metadata, and still allows us to use content references stored in YAML.
We hit the core styling and structure that we need with a solution that is relatively easy to write and edit in. There are certainly trade-offs because of the simplicity of Markdown. But, the benefits of collaboration are important enough to make it worthwhile.