Documenting for Continuous Delivery


#1

A couple years ago Atlassian presented on documenting in a continuous delivery environment. They shared some great tips, and I was wondering if there are other companies and teams documenting in this type of environment.

If so, what does your content planning and creation process look like?
How do you align with your software development teams?
How robust are your tools? I’m particularly interested if anyone has been successful in a DITA/CMS toolchain.

Any other tips or contacts are welcome!


#2

Are you talking about in terms of publishing? I work for CircleCI and as you would expect, we use CI/CD for practically everything including Documentation.

Our docs are built with Jekyll, on a CI server, tested for proper HTML, broken links, etc, and then if all tests pass, is published on AWS.

Is this what you’re talking about or did you meant documentation where the subject is CI?


#3

Yes, I meant in regards to publishing. Thanks for sharing!

What are the expectations for product documentation? For example, does the doc set strive for an MVP-level to release at same time as the new version, and then the rest of the documentation is more reactive to what customers ask? Or, do you try to document as much as possible to circumvent support calls once there’s a release? I would imagine in a CI/CD environment, you’re hearing from the user more often to see what to work on next.

I’m also interested in how you use the CI server… Do you continuously push your content to a server to validate it, and then it’s ready to go live? Who sets that up for you-- the documentation team or another department?

Our company is in the process of switching to a CI/CD environment, so everyone is learning at the same time, which makes it difficult to find the resources to create a system that focuses on the docs. Do you plug in with the source code of the product, or is documentation created and tested separately?


#4

We release weekly. We have levels of release: beta (don’t use in production, subject to change w/out notice). For Beta, only platform doc is written, and it’s MVP doc for sure. Early Access is the stage where we deliver full doc for both platform and product (GA sometimes requires changes, sometimes not).

We have a simple tool chain and no translation. I don’t know what we’ll do when we tackle translation.

Platform doc uses the development tools (git, GitHub, doc in markdown, lots of scripts and processes written outside of doc team to turn markdown into static web site). Product doc uses tech writer tools, and only uses git for source control.

It’s wicked challenging. Pretty sure we don’t have all the answers, hope someone does!


#5

I’ve just started automating our docs with Jenkins. I used this blog to get it started, and it’s been running successfully:
http://3di.com.pl/automate-documentation-publishing-jenkins/

The steps I’ve taken are:
1 Set up a VM with Bitnami Jenkins, Flare, and Cloudberry Drive.
2 Have a daily Jenkins build that does the following:
a - pull from SVN
b - build Flare
c - copy to the Cloudberry Drive (which is our publish to the cloud).

This is what we do for our daily staging for QA. We’ll probably build a parrallel job to run for our production pushes.