: What is considered an acceptable length for a technical document? I have written dozens of technical and requirement specifications, and edited dozens more in 8+ years of engineering. The largest

Vote Up Vote Down

I think the important metric is “is it usable?” I think it is really about the quality and organization of the table of contents and the index and the data. It doesn’t matter if it is 10,000 pages if the reader can find the 3 useful pages they need easily in a short time. On the other hand, a confusing, disorganized 200 page document with mediocre data might frustrate readers and not help them at all.

Second metric to me would be “is it maintainable?” If it is so big that it can’t be well-maintained and parts are always out of date, it will just decay and decay.

So if you go on the basis of usability and maintainability, you might determine that 1 giant book is better off as 10 shorter books. The separate books act as a meta-index. The reader or maintainer can ignore the other 9 books when appropriate.

It sounds like the document is frustrating you, so maybe it is frustrating others also. You might do a survey of readers and maintainers to see what their complaints are, ask them a few questions. That could generate the hard data you need to suggest an improvement project, and maybe give you a list of things to focus on improving also.

(0)

Vote Up Vote Down

Acceptable to whom? As with "quality", we are talking about a characteristic that is defined by the context. Whatever the customer, user or other stakeholder accepts is "acceptable.

On the other hand, from a professional perspective there's a lot of experience you can draw on to suggest what users may find acceptable - without any guarantee that the customer agrees!

Finally, technical writing should aim to be comprehensive - the "length" or "size" (how do you measure these exactly?) of a document can be correlated against the basic criterion "did I describe the whole topic?" - i.e. all the features; enough details for the user to understand the concept; links to all relevant references.

So - "how heavy is your topic"? It's an interplay of internal and external factors, case-by-case. Hence the profession exists.

(0)

Vote Up Vote Down

I really don't think there is an answer. Working in a technical field myself, I have been frustrated by documentation that is too short, and doesn't provide answers to the questions I'm looking for but also seen documentation that is simply too long and makes it impossible to find the quick answers you usually need as a reference.

I'd expect the documentation for a lightswitch to be reasonably short. Whereas the documentation for a nuclear submarine should be considerable.

Documentation should simply be functional when used by someone with the appropriate skill level. After that the length is irrelevant.

(0)

Vote Up Vote Down

It all depends. Size doesn't matter so much as what you do with it. ;)

In my experience, what's been important is that the technical document serves the need of people in the organization to communicate, so that rather than asking a person to explain something, one can just look at the document. If that process is not happening as needed, or not happening well, then something needs fixed (but the issue might not be length, it could be searchability) because the document isn't communicating. Otherwise, I'd suggest letting them be.

(0)