Comments on Six Tips for Improving Your Design Documentation

Brian Krause — Thu, 23 Aug 2007 20:25:51 GMT

Ryan, thanks for the citation, part of a useful article.

I go even a bit farther on “use the present tense, active voice.” I go so far as to write in the second person, for example, “your available balance appears at the top of the report.” (Compared to, “The user’s available balance….”) This avoids the stuffy phrase “the user,” he/she pronoun issues, and I think is less distracting than using character names. In fact, I’d say it’s almost unnoticeable if you do it this way. It also lets harried tech writers lift from the spec—think of it as the first draft or base of the user manual.

VegasLaunch — Fri, 26 Jan 2007 14:51:23 GMT

Updating a document and maintaining document development through theages that is not personality based is not covered. This process only works for those who want to keep track, a true solution will encompass both personality types.

ryan olshavsky — Wed, 30 Jan 2008 20:38:37 GMT

Thanks bmundy! You raise a good question. It’s true, the type of document I talk about in the article is typically oriented less toward programmers than toward the decision makers (who are more likely to be product managers, executives, or possibly even other designers). That audience is generally more receptive to narrative presentation, for example. Tips 2 and 3, on the other hand, are probably less interesting or useful in documentation for developers (the other tips, I’d argue, are useful no matter what audience).

But to answer your question (in a round-about way, and with another question): What do you mean by a “technical” document? Do you mean something that tells the developer exactly what they’re supposed to code, and how, or something that provides detailed specifics about how the design looks and behaves? If they’re demanding the former, I’d suggest pushing back—the technical requirements document should really be created by the developers, based on their technical needs and objectives. If they’re asking for the latter, then, yes, you probably want to create a separate detailed design document. I’ve seen that document variously called the “Form & Behavior Specification,” “Design Specification,” and “Functional Specification.”

That may not be the answer you wanted, since it implies doing more work. But you can avoid a lot of it by using the preceding, more narrative-based document to inform the content of the design spec. The key difference between the two docs, though, is that while the first doc will likely be organized around how the *user* sees the product, the spec should be organized (as much as possible) around how it will be built. So, if you have a website with 5 distinct sections, each one would probably be represented by its own section in the design spec. And the details of the design would be presented within the context of those sections. A general structure I’ve used for the specifications is: Section > Component > Details > Behaviors.

Developers usually need a document that is easily referenced and organized logically so they can (ideally) have it sitting next to them as they code.

All of which is to say: yes, I’d recommend writing two documents. :)

bmundy — Fri, 26 Jan 2007 14:51:22 GMT

Ryan,

I enjoyed your article. We are currently in the process of evaluating the usability/utility of our documentation (how well can those reading the doc translate, absorb, produce), so your article is timely :) Something we are finding is that the type of document you describe works well for our designers that produce the prototypes, but is less useful for the developers who actually write the code. The developers prefer more of a stripped down -just the requirements- technical document. Would you suggest two documents in this situation?