Why Implementing Continuous Integration (CI) Server for Documentation Deliverables is Need of the Hour

The other day, one of my colleagues explained to me a scenario encountered at a customer site: A secondary developer used a sample code snippet from the user guide, but that sample code is faulty. The annoyed secondary developer raised a red flag for the incorrect sample code in the user documentation. After a chain of discussions, it was discovered that the classes and methods used in the code snippet were deprecated in the latest release. The change is not communicated to the document writer and reviewers focused mostly on the newly developed contents. In RCA, it was highlighted that testing complete document suites for each release is a cumbersome process, especially when the teams practicing Agile methods, where release cycles are short and frequent. Performing tests such as hyperlink validation, APIs correctness, code samples verification, language/style guides compliance verification, and so on manually for the complete document suites for each release is time-consuming, expensive, and dedicated resources are required.

Therefore, we were thinking to automate certain repetitive tasks and decided to implement a continuous integration server for technical documentation deliverables. In other words, we want to have a machine called CIS, to do all integrations and validations repeatedly. Nonetheless, this is not something new to the documentation industry, as many organizations are implementing CIS for technical publications. We did exploratory research to understand the best practices, what problems CIS can solve, what all applicable for us, how a typical CI setup can look like, so on and so forth. Here are some of the exploratory research outcomes:

Solve problems rapidly

When you frequently integrate documentation modules such as source documents, code snippets, API documents; and documentation tools such as API checker, Link checker, Grammar and style guide assistant tool, and Code snippet integrator, it is significantly easy to find what went wrong. Also, the documentation team is in full control. The dashboards in the CIS answer you to the questions like— How much of the content have we developed, are there any broken links, are there any code integration errors, so on and so forth.

CIS integration for documentation deliverables brings multiple benefits including:

• Integration becomes a non-event—Integration is no longer an activity for a writer.
• Reduces risks—Early discovery of defects. The health of the library is measurable.
• Reduces repetitive manual processes—CI saves time, cost, and effort. Also, the reduction of resources on repetitive processes, allows people to do more new and high-value work.
• Enables better project visibility—Provides management with a snapshot of the project status and reduces the time spent on validating documentation and integration errors.
• Establishes greater product confidence—Tests are run against the documentation suites to verify the behavior, which gives greater confidence in its accuracy.

CIS Setup

The continuous integration process for delivering quality documentation acts as a process of putting all documentation modules together and verifying that the library (documentation suite build) works as a cohesive unit.

1. When a document writer check-in a document to the version control repository, the CI server detects that changes have occurred in the version control repository.
2. CI server retrieves the latest copy of the documents from the repository and fetches the latest code samples/API documents from the Development build machine.
3. CI integrates source documents and code samples/API documents and then builds a documentation suite (library).
4. Once the library is built, CIS execute documentation tools to check for broken links, language or style non-compliance issues, validate sample APIs, and so on.
5. CI server publishes a report that consists of a library link and library health report.
6. Finally, a notification email will be sent to the specified project members.

Here, the model is to automate everything end-to-end (without any manual intervention)—Compiling, Packaging, Validating, and Publishing.

Best Practices

• Get everything you need into source control and build the whole system with a single command.
• Everyone check-in every day: Frequent check-in encourages writers to break down their work into small chunks. This helps to track progress and provides a sense of achievement.
• Ensure that the build takes a maximum of ten minutes to complete. If the build takes too long to execute, try to build the system parallel for independent parts
• Make the state of the build as visible as possible.
• Give release only if the CI server is Green.

CIS for documentation deliverables is not just a tool; it is a cultural change.