Documentation teams who work for Cloud companies all face the same challenge: how can they keep up with the pace of software updates? If you are involved in product management or documentation in the software industry, Internet Services, or IT at large, this is not news to you. The pressure of delivering new features is high on Web Apps and SaaS solutions. Agile methodologies and DevOps culture are becoming mainstream and daily delivery, if not continuous delivery, is the new norm. In this process, offering up-to-date documentation is not optional. But how can Cloud Companies deliver accurate content in near real-time? One solution is to involve developers in tech doc writing. This is one of the most solid options and a good way to sync documentation with the product releases. But if you are aiming for adoption and efficiency, you must strongly consider the process and tools you will use. Let’s see how Markdown can be the secret weapon to your Technical Documentation Continuous Integration.
Developers writing the doc? Really?
Before speaking of tools, let’s speak about the documentation production process. Assuming that developers will write the tech doc may sound a bit far-fetched if not entirely unrealistic. The point, though, is not to have the developers to handle the complete writing process for a given topic, from the initial conception to the polishing of the text. Not all developers have writing skills, nor do they desperately want to acquire those skills. But they own product knowledge and they know for sure how the product is designed and how it works, in real-time. The idea is to implement an alternative and collaborative work process between developers and writers that corresponds better to the constraints and pace of CI/CD. In the classic way of producing documentation, tech writers collect information by interviewing the subject matter experts (SMEs), they write the doc, and the SMEs (in this case the developers) review. Adopting this configuration, producing more and faster means hiring more tech writers. A lot more. An alternative way of producing more tech doc faster is to have the SMEs contribute to the documentation process, but at a stage where it makes more sense for everyone: content writers define what needs to be written and how, developers write in sync with their code, and tech writers review. It’s not scaling up as much as it is scaling out. The benefits of scaling out are huge. You can produce faster with the same team, create a more diverse content library, and leverage the expertise of your individual talents at their best. And if you think about it, developers already write a lot of content. Consider all the README files that are stored somewhere but are never read. And not only README files: there is a ton of content written by developers in all software companies. Of course, if you asked them, writing documentation won’t emerge as the developers preferred task. But what would be even more frustrating for them would be to write content that is never used by anyone. So documenting their code may not be the biggest issue for developers when asked to contribute to the doc, in particular if they are not requested to polish it to a tech writer’s standards. But writing in DITA, using some specific authoring tools is definitely a no-go, and that’s why tools can matter as much as process does.
Why is Markdown a good fit for developers’ contributions?
If you want SMEs to contribute to the tech documentation, you need to let them use their usual tool or you’ll be facing massive slow-downs in your process, if not the complete failure of the project. Markdown is a popular and lightweight markup language amongst developers. It is extremely easy to use, and very simple to learn for those who have never worked with it before. It is perfectly natural for developers to embrace, but also has fans amongst consultants and tech writers. Beyond the ease of the syntax itself, there is no barrier to entry with Markdown: it is not another tool, not another system to install and maintain, and you don’t need to get IT authorizations or secure a budget. Markdown can be edited with any text editor and that certainly plays a big role in its adoption. 
But one of the strongest points with Markdown is its native integration with the most common CI tools like GitHub, Gitlab and more. This makes it the perfect fit for continuous content integration with product changes. It makes it possible to perfectly sync content production, tests and validation with the code in a single process.
Continuous Content Delivery with Markdown
Producing technical documentation at the same pace as product releases is one thing. Delivering it to the users in the same move is another. Fast-paced content production requires dynamic publishing. You cannot really afford to stick to the old-fashioned publishing, create and then deliver PDF documents for each and any product, branch, and version whenever you add a feature or fix a bug. If you still spend so much time publishing content, what’s the point of producing it in real-time? Real-time publishing is what Content Delivery Platforms such as Fluid Topics enable. These platforms are designed to collect content from the different repositories where it’s produced and where it lies, transform it into a unified knowledge hub, and delivers it dynamically to all needed digital channels. Fluid Topics provides a native Markdown connector that allows you to automate your content publishing in sync with your code and integrated with your CI/CD process. The release of a new version or the update of a branch can trigger the publishing of the corresponding content to the right users and the right place: be it for staging or production environments, to a limited audience or publicly, for a specific version or for all versions that are impacted by the code change. You define the rules and Fluid Topics automates the publishing to your documentation portal, to your website, or even to your online help. 
Conclusion
Whether from the perspective of adoption or from a CI/CD technical standpoint, Markdown is an excellent option to choose in order to include developers in content creation and achieve real-time tech doc production. Dynamic content delivery closes the loop of an integrated code-and-content continuous delivery process. And it’s more than theory: we, and many of our customers from the software industry have already implemented it. If you want to have a closer look at what the entire process could look like for your organization, we have highlighted two use cases in a recent webinar, available here.
Want to learn more?
About The Author
