new documentation should always augment the status quo

In my line of work, I often need to create documentation for clients.

Documentation in general is a Good Thing™.

But good documentation’s goal should always be to augment and improve upon what already exists – not to supplant, downgrade, or muddle what already exists.

A prime example of this has come up with a client partner recently. They asked for “as built” documentation. They failed to define that term. It turns out that their definition of “as built” is a “screenshot-by-screenshot” replacement of the vendor-supplied installation and configuration manuals.

This is a phenomenal waste of time, effort, and space. “As built” should mean to note any deltas or site-specific configurations that vary from or augment the vendor-supplied manuals.

Why is this the case? Because recreating vendor documentation means attempting to do a better job of documenting a product then the people who wrote it! The odds of you being able to do this are extremely low.

In fact, I’d go so far as to say you cannot do it. Ever. The vendor has dozens, scores, hundreds, or even thousands of man-years of experience with the product across the whole team. They know where the source code sits, and can reference it directly. They have the ability to truly say what is and what is not authoritative on the product.

You will never be able to outdo them. Even if you have been using the product since it was in pre-alpha form, you cannot, as one person (or even an outside team of people), possibly have as much experience as the development and documentation teams that design, build, and describe the toolset. They don’t just hold the trump car, they are the trump card when it comes to how something works.

Whenever you document a process, make sure that you document anything that is site-specific about what you did. Make sure you reference the vendor’s materials as often as feasible to make sure you backup your claims and directions with authoritative data.

But don’t worry about recreating what the vendor has already done – your documentation, in this regard, will never be as good as the vendor’s: they publish errata notices, updates, etc. You have to do the same to have a remote chance of matching them.

You will not be successful.

Focus instead on making great documentation that goes hand-in-hand with vendor materials to supplement them; don’t try to supplant them.