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?

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.

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.