Tools are not documentation

I’ve been running into an issue that I’m not sure how to get around — mostly because it’s somewhat political, and I don’t like to play the political game — and it’s frustrating. Because the issue is work-related, I am intentionally skimping on the details, but I’ll give you the gist of what I’m dealing with.

I’m trying to document a procedure for engineers to obtain temporary administrative access. In order to do so, the engineer needs to fill out a form to request the access. I’m trying to write about how to find and complete the form.

I spoke to the form’s owner (this is where the political part comes in). I explained what I was doing. However, he keeps insisting: “it doesn’t have to be documented, because the form is the documentation.”

He showed me a screen shot of text on the form that explains how the particular request works. The text made a lot of sense, and it would have been ideal to fulfill at least part (if not most) of my needs. I decided that I would create a reference to it. So I looked around the form for it… and could not find it anywhere.

He finally told me that “you had to click a specific button on the form to view the text.”

How was I (or anyone) supposed to know that? (Answer: you couldn’t.) Just by that alone, he contradicted his statement that the form is documentation. (It isn’t.) I wrote about this earlier; he is under the (potentially) dangerous assumption that everything on it is obvious. (Disclosure: the form in question is exactly the same one that I wrote about in the previous article.) He keeps insisting that the form is the documentation. But in spite of that, he gets frustrated that his department continually fields questions about how to do things that could be handled by the form — if it was properly documented. if the form actually was the documentation, it violates a major principle of technical writing: documentation is like a joke. If you have to explain it, it doesn’t work.

Now, I will mention that I like the guy. He’s personable and pleasant, and I do enjoy talking to him. But he is stubbornly clinging to his belief that his tool is the documentation. I try to explain to him that it isn’t, but he won’t have it. And I have to admit that I’m not sure how to handle it.

I pinged the project manager to get her thoughts on how to handle this (I’m still waiting to hear back from her as I write this). She has a better rapport with this person than I do, so she might have some insight as to how to handle this. Nevertheless, I think this is another case where you need to keep an open mind to improve a product, and realize that tools are not necessarily obvious in how to use them. Even a hammer can do more than just drive a nail.

Advertisement