What is considered an acceptable length for a technical document?

Question

I have written dozens of technical and requirement specifications, and edited dozens more in 8+ years of engineering. The largest I have drafted was perhaps 100 pages, but maybe 30-50% of it was diagrams and tables. Most were anywhere from 5-25 pages.

My current position has documents that, if removed from the database and printed out, would be twice as long as War and Peace (I did the math). That is one supplementary document for one particular feature in one particular system.

I want to know if there is a standard length that is considered 'usable' for a technical document. I would prefer to have documents broken down into smaller chunks, but I don't know that I could convince my current employer that this is something they should pursue unless there is some data to back it up.

Answer 1

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.

Answer 2

(Short) length of technical documentation is a must if that documentation is printed to accompany a product sold to an end user. You cannot sell a pocked digital camera with a five volume textbook on how to handle it. But I'm sure you have also experienced situations where the documentation was brief to the point of becoming confusing.

If the documentation is purely digital, there is no reason at all to limit "length". The only consideration is usefulness.

Unlike Michael B I don't think that volume decreases "findability". That solely depends on proper indexing and an "intelligent" search algorithm – both digital and in print.

Using the example of the pocket camera, there really is no reason not to go beyond the mere technical explanations and include some basic information on how shutter and sharpness of an image relate to each other, or what the numbers on the shutter mean. I always forget those things, and having them handy with the manual of my camera would be a nice feature. This will bloat the documentation, but make it more useful for the target audience of amateur photographers.

(Good) illustrations, detailed examples and other non-basic information also helps understanding, while it drastically increases the size of the documentation. But in a digital (hypertext) manual you can easily "switch" those features on or off with a simple button, essentially creating a short-and-long document in one document.

Of course you might want to print out your documentation for the purpose of backing it up or getting an overview, but that is one special use that should not dictate what the end user gets. Only if the end user gets a printed copy should length be a factor. Otherwise, as I said, the only relevant question is wether the information is useful or not. If it is useful, put it in.

Answer 3

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.

Answer 4

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.

Answer 5

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.