Do not leave the documentation until last

March 6, 2009

Late last year I was working on a big project where the application was customized to each clients’ specifications. In a meeting, one of the developers brought up the inadequate time allocated for testing and QA and how it was critical to allow sufficient time for testing so that big bugs and errors didn’t go out  to clients who had paid a lot of money for the software.

I couldn’t let the opportunity go by to add something about allowing sufficient time for documentation too, especially as this documentation was also customized for the client. (Note: There were some 20+ developers and implementers on this project, with a part-time tester and a part-time technical writer [me]. I’ve written before about treating the documentation writing  process like the code writing process…)

Here’s part of what I emailed the project team about allowing sufficient time for documentation:

Can I add that documentation is also something that can’t be tacked on at the end as the product is about to walk out the door. There’s often a legal or contractual requirement to provide user documentation, whether anyone reads it or not. And it doesn’t just happen. You can’t have 6 developers or implementers working on something for 3 months (18 person months), then expect that it can be documented (and undergo a thorough technical review) in a couple of days, especially if the thing being created is unfamiliar to the technical writer.

While I have a common set of topics for [the base product] and an authoring tool that is set up for content reuse, I can’t just create custom documentation for a client in a few minutes. It takes time to set up their templates, take screen shots of their icons and screens, and write stuff specific to them into their doco. Actually, that’s the easy part…

The hard part (well, not hard, but very time consuming) is documenting and getting graphics for specific customer workflows. Too often this is a ‘rush job’, and sometimes the person who understands the workflow is not available to get clarification from (overseas, vacation, whatever). There’s no blame attached to this — I’m just stating reality as I see it.

As an example, [my boss] asked me last week if I could work later this week instead of my normal days because the UAT (user acceptance testing) documentation for [clients A and B] was going to loom large. That fit in with my schedule, but it’s now the middle of Thursday and I don’t have anything yet to work on. I understand that builds break, that things aren’t 100% ready, but when UAT for the client is next week and the UAT doco has to be completed — and reviewed! — before going with the implementation team to the client, that puts enormous pressure on those of us at the end of the chain. When I get the draft of the changes I will do my absolute best to get it out on time. But it shouldn’t be like this ALL THE TIME. Too often people have taken doco home over the weekend to review in amongst the kids, or come in to work at 6am to finalize the doco so it could be emailed to the guys on site as it couldn’t be finished before they got on the plane.

The quality suffers when something is done in a hurry and insufficient time is allowed for thorough review — whether that’s software, documentation, or testing.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: