How to do design automation: DocGen concept diagram

I’m a bit of a documentation nerd. Writing technical documentation is a boring, but often necessary, job that other people hate doing. I’m good at it. I also care about it, for some unfathomable reason. This combination means that I’m usually the guy who ends up doing it.

Now I hate boring and repetitive tasks, so whenever I have one that needs doing, I tend to automate it if I can. This has proven a challenge when it comes to IT documentation. I make heavy use of styles in Word (for some godforsaken reason every company insists on using a tool designed for typing inter-office memos as a technical document publishing system. ARGH!) and set up nice templates so the documents look good. But Word doesn’t scale well. It tends to break badly when documents get large, or if you try to use inter-linking between them. And try changing the corporate logo in 80 documents.

This annoyed me no end, and I figured there had to be a better way. There is, but it requires a completely different approach to doing documentation for IT systems.

The Problem

I’ve worked with several large companies that have well structured documentation (Solution Architecture, Detailed Design, Change Implementation Plan, etc.) for the systems they design. I set them up in a couple of cases. The designs themselves are usually standardised so that you can scale; Toyota doesn’t do custom pin-striping on every Camry for a reason.

After a year or two, you have several hundred designs, each one with 5-10 documents describing it. That’s thousands of documents that all need to be managed and maintained. If the process isn’t efficient, it gets unwieldy really fast. That’s happened to at least one documentation template I created. It was fine for the first 3, but it didn’t scale well after 300.

And you have a bunch of different people working on this stuff. People tend to approach things differently, so you end up with similar designs, but different people change things in different ways. Word documents are incredibly easy to break in horrible, unfixable ways, and this is usually what happens. All it takes is for one person to screw up the styles and the document becomes a disgusting, unreadable mess.

You also tend to have the same information repeated in multiple places within a document, or between documents. You can use document properties/variables, or set up a mail-merge type thing, but that requires advanced knowledge of the tool by the people using it. Most don’t, so you end up with a lot of cutting and pasting going on. And people make mistakes, so there are lots of typos and missing or wrong information.

So after 6 months to a year, you have a variety of documents that aren’t consistent, look awful, and that are painful to use. It all gets too hard, so without iron-fisted discipline, people stop using the documents properly, and they become worse than worthless. You’d be better off, in many cases, not bothering with it at all.

But there is an alternative.

A Different Way

If you think of documentation as a software product, and not just a bunch of random memos, the work of an IT infrastructure group starts to look quite different.

Instead of writing a bunch of memos, they’re writing software. Design documentation is instructions on how to put something together and how it works. Wouldn’t it be great if you could use these instructions to automate the building of systems? And maybe spit out the documentation as well?

Then, rather than documentation being a painful afterthought that never gets done properly because it’s “not important”, it becomes the easiest way to get the system built. You write up the design, hit the big, green Go button, and voilà! Instant IT system. With all the documentation to go with it. All looking the same, all matching the design exactly.

Impossible? Nope. I’ve done it. There’s a previous client who’s been using this system for over a year.

The DocGen Design System

The DocGen IT workflow

I call it DocGen. You feed in an XML description of your system design and it spits out PDF human readable documents you can give to your customers.

It also generates the doco you give to your engineers so they can configure their servers, databases and switch gear.

It also generates the exact commands needed to configure your kit to implement the design.

I’ve been drawing up the workflow over there to the right on whiteboards for the past couple of years whenever automation comes up in meetings. It shows you how DocGen fits into your existing IT systems, but can make you orders of magnitude more efficient. The cost savings are huge.

Find Out More

Find out more about DocGen by visiting http://docgen.eigenmagic.com.

Or, email me at [email protected].