How to Scale Documentation, Part 4

My Input phase is now as efficient as I can make it.  What about the Delivery phase?

Already?  That was quick....


Ok, it's not quite as efficient as it could be, but we're getting there.  It takes time to get authorisation for new licenses, a better build server, etc, etc, etc.....

Tell me about it.  But you're making progress, which is positive.  Let's talk about Delivery then.


Yes please.

In Part 3 I said that you need to replace the following things from your processes with efficient and effective tools, processes, procedures and standards:

1. Unnecessary/complicated process steps;
2. Bottlenecks;
3. Anything done by humans which is better done by a machine;
4. Decision making.

I seem to remember you also said that I'd spend more time on automation in the Delivery phase?

Good memory, nice to see you're taking this in. Yes, whereas Input - the creation and maintenance of your documentation - requires creativity and (a certain level of) decision making, Delivery should be a "dumb" process.  By that I mean that it shouldn't require much, if any, thought once you've got an effective process in place.


That seems a bit odd.  You said that all 3 parts of the cycle were equally critical; now you're saying that Delivery is just a "dumb process"?

No, I'm saying Delivery is a "dumb" process.  The placement of the quote marks is important!  A "dumb process" is a process that seems stupid.  A "dumb" process is one that doesn't require any thought to follow.  If Input is the phase where you carefully build something, Delivery is the phase where you cover it in bubble wrap and hand it over to a courier to deliver.  You're not interested in the mechanics of the courier's van, or whether it's a petrol or diesel van, or the route they take, or what sat-nav they use, or how often they have to take a break to comply with legal regulations for couriers.  You're just interested in the end result, which is that the customer gets the correct package, on time, and undamaged.

(For those writers who moonlight as couriers, I'm not suggesting your second job doesn't require any thought, just that the people who use your services are paying you so that they don't have to think about this aspect of their business.)


Nice back-covering at the end there.

Thanks, I've learnt the hard way not to annoy couriers.  Anyway, the point is that once your Delivery system is set up, you should be able to hit a button, metaphorically and preferably literally, and then not worry about it. That doesn't mean you don't need to design the Delivery phase carefully, but it does mean that you can rely on automation for a lot more of the Delivery phase than you can with the Input phase.

This has the significant advantage that it's normally much easier to scale an automated process than a manual one, because computers are cheap and ubiquitous whereas people to run a manual process are not.


That makes sense, but when does the Delivery phase start?  What's the transition point from Input to Delivery?

Good question.   The final part of the Input phase is the proofreading and review stage.  The Delivery phase starts when you have content that you're ready to release to customers.  That's not internal stakeholders - e.g. product management, support, etc - who might point out errors or omissions, that's your actual customers who are getting the finished, can't-be-changed, officially-versioned content that people who've paid you money will be getting with a release of the software.  Obviously if all of your customers are internal they won't have paid, but the important distinction is between the final version of the content that hasn't been officially released, and the version of the content that will be officially released.


Why have you started saying "content" instead of "documentation"?

Because the Delivery phase consists of 2 parts: Build and Deploy.  The content will be built into documentation in whatever form you use (PDF, HTML, CHM, etc) and then deployed to the customers. Whilst there might be a manual check on the final documentation between building and deploying, the proofreading and review stage of the Input phase, along with your automated build stage in the Delivery phase, should be robust enough that the release build will only need a minimal paranoia check. 


Assume I'm at that stage with content ready to be built.  How do I make sure my Delivery can scale?

Because there are only Build and Deploy stages, there shouldn't be many steps to go through for Delivery.  Therefore you can focus on making both stages as automated as possible, whilst removing any potential bottlenecks.  The good news is that if you have created a fully-automated Delivery phase the only bottlenecks should be ones that can be solved with additional resources:

• Appropriate licenses for tools that build and deploy the documentation;
• Bandwidth for uploading/downloading the documentation;
• Processing power to build the documentation.

Ideally your Delivery automation will all be initiated in an automatic chain based on an entry action such as uploading your content to a specific folder on the build server. For example, your automation could be:

1. You upload content to "Auto-Build" folder on build server.
2. Process that polls "Auto-Build" folder finds the new content and kicks off a documentation build via a script that uses the command line commands for your help authoring tool.
3. Once the build is completed the script deploys the contents of the newly created documentation folder to the live web server.
4. Your customers are told about the new documentation either by an RSS feed or an automatically generated email that is sent whenever something is uploaded to the live web server.

I've got so many questions! A process that polls a folder? Command line commands? Automatically deploys content to a live web server? How do I do all of that??

Yeah, you're just a writer, how are YOU supposed to do all this stuff?  


Exactly! This is way out of my league!

Good news: No, it's not, stop being so defeatist!  You can use PowerShell to watch a folder and kick off an action - such as a command line script - when the contents change.  Writing a script (also known as a batch file) to run on the command line is not hugely difficult, and help authoring tools normally provide command line tools for building documentation, like this for Flare or this for RoboHelp.  Finally, you can copy files and folders from the command line; here's the syntax.

I won't say that any of that can be done in 5 minutes if you've never done it before, but if you're willing to put the effort in then the ROI will be immense and your scalability will be massively increased.  Plus you work with developers, and every software house has plenty of people who can write batch files so you should be able to get help, especially when you're trying to troubleshoot a problem.  


Well....ok, maybe I overreacted a bit there....

No problem, we've all panicked a bit at one point or another.  But if you don't try, you'll never learn!


Agreed.  Now, what was that about a live web server? 

As much as possible your documentation should be O/S and application agnostic, so the best way to provide it is in web format.  This means some combination of HTML, XML, XHTML, CSS and JavaScript, which any and all browsers can display,

However, this is a surprisingly big topic so I'll deal with it in the next post.  What's important right now is that you understand that automation has the ability to make your Delivery phase quicker, easier and more scalable.  We'll look at the specifics of what to deliver to customers, and where there are mutual benefits to both you and the customer of delivering in certain way, once you've got your head round automation.


It does look a bit scary, but I can see how automation might help a lot.

Excellent, give it a go.  You know it makes sense.


I'm willing to try.  Although it would help if I understood more about why I need a live web server and why I can't just build whatever targets I'm asked for.

I can understand that.  Stand by, we'll look at deployment options in Part 5.