How to Scale Documentation, Part 5

So, deployment....

Yes.  How's the build part going?


I think I'm getting my head around the automation that you talked about in your last post, but without knowing what the end goal is, it's hard to design it properly.

If you've never done any form of automation before then it's important to understand the concept and to try it out, even if you don't know the final goal yet.  A musician can play anything once they've mastered the instrument!


Well, I haven't mastered automation yet, but I'm getting there.  I've also got deadlines to hit, so if we could talk about deployment now that would be great....

I hear you, loud and clear.  As I said in Part 4, your documentation should be O/S and application agnostic as much as possible.  This means that the format you choose needs to be as open and non-proprietary as possible, which means you should use web format, i.e. HTML/XML, CSS and JavaScript.


Wait, why is being O/S and application agnostic so important?

Because if you create your documentation in a format that is primarily designed for one O/S - e.g. CHM - then no matter how good the viewers are in other operating systems you can't always be sure that viewers are a) able to read it on every machine without having to install software to read it, which sucks for them, and b) going to see the same layout and formatting on every machine they read it on.

Secondly, you're dependent on the features that the proprietor decides to give you when using that format, and those features can be taken away or changed at a moment's notice without you having any choice. Believe me when I say that upgrading to the new version of the build tool and finding that they've deprecated functionality that you relied on is not fun.  At all.

Thirdly, proprietary formats can be withdrawn without notice at any time, plus as long as you use that format you're tied to that supplier.  The older a proprietary format gets, the more likely it is that it will be superseded by newer formats and therefore the more likely that both the supplier and others involved in the format ecosystem who provide tools to read and edit the format will eventually stop supporting it in favour of something more profitable.


All good points.  But why web format?  Why not PDF?  Why not web format AND PDF?

There's 2 questions there:

1. Why web format as opposed to anything else, and
2. Why a single format?

To answer in reverse order, the benefits of a single format are:

1. Only 1 set of documentation to layout, format, review, proofread, build, deploy and maintain;
2. Only 1 help authoring tool (or help authoring suite) is needed to cover the whole of the documentation;
3. Customers never have to work out which is the right format for them.

Part of scalability is keeping each step of your process as simple as possible, and then keeping the number of steps down to a minimum.  Having more than one build target - e.g. HTML, CHM, PDF - increases both the number of steps and the complexity of the steps (especially when it comes to reviewing and proofreading the documentation in more than one format).  

The benefits of using web format, as opposed to PDF or any other open format, are that: 

1. Every computer, including servers, comes with a browser that allows them to read web format without installing any software, plugins or extensions;
2.  Web format can be read either from an external website or from an internal server (if there are limitations that a customer places on the external connectivity of their database or application server, for example);
3.  Browsers are backwards-compatible for older versions of HTML/XML, CSS and JavaScript (at least up to a point) and newer versions of HTML have appeared on average about once every 4.5 years, so there's little danger of your documentation being unreadable for - realistically - a decade, and probably a lot longer than that;
4. Because web format is so widely-used there are a myriad tools you can use to write/generate/build/deploy it, and that's before we get onto the benefits of using DITA, which is an XML format and therefore ripe for web deployment.

Are there scalability benefits to using web format though? 

Yes, and this is where the live web server that we mentioned in Part 4 comes into play.  The most scalable solution is to provide your documentation in web format and put it on the internet for your customers to access (behind a login if necessary).  If you have customers that might need the documentation locally, you can also provide a copy with the software that can be deployed on the customer's intranet.  This means you still only build one target, you just copy it to the live web server and also to the software build server.

This gives you:

1. Smaller, quicker install (if the customer doesn't need the documentation locally);
2. The ability to embed files, e.g. video, of any size;
3. Dynamic updating of the documentation rather than waiting for a release;
4. Gathering of stats to identify pain points in your product.

All of these points will help you scale your documentation by giving you a single documentation set to maintain.  You also get the additional benefits of identifying pain points in your product by gathering usage stats, and you get lots of scope for gathering both implicit and explicit feedback.


Feedback as in the 3rd part of the documentation cycle?

Well spotted.  Yes, if you've scaled Input and Delivery then the 3rd and final part to complete the loop is Feedback.  Having your documentation online for customers to access will definitely help you with that because your customers are already coming to your documentation, you've just got to take advantage of that and get the feedback from them whilst they're there.


Ahhhh, you cunning fox.  It's all starting to get a bit clearer now.

This kind of system isn't just knocked together in 5 minutes on the back of a napkin you know.  There's some actual thought gone into this.


So I'm starting to realise.  How do I start getting feedback then?

Easy, my young padawan.  The force is strong with you, but you're not a Jedi yet.


Star Wars? Really?

Just trying to provide a bit of levity, but suit yourself.  We'll take a look at Feedback next time.


Yes, Master.

Stop taking the mick.


*chuckle*