Quick and Easy Document Specifications

An introduction to doc specs, what they contain, and why you want to have them.

Documents Have a Purpose

Technical documents have a purpose. If you don’t understand the purpose of a document before you start writing it, you may deliver the wrong document. A document specification (doc spec) should define your document before you have a chance to get into trouble. A doc spec doesn’t have to be long or a pain in the patootie. It can be written on the back of a napkin and take three minutes. It can be a two paragraph “Did I get it right?” email. But if it doesn’t exist at all, you are asking for trouble.

Elements of a Doc Spec

At Expert Support, our doc specs have six parts. You can add more parts, but these six have served us well.

• Business objectives
• Audience
• Technical objectives
• Pattern of use
• Content
• Delivery medium

Each of these parts is described below.

Business Objectives

Why did the customer order this document? Usually the doc is part of a product and enables the user to understand some component or process having to do with that product. Some examples of business objectives are:

• Installation manual: To allow customers to quickly and easily install the XXX software product suite.
• API reference: To describe, in detail, all the interface objects and methods available for customer use and to enable users to make use of the API without having to call support for detailed information.
• Tutorial: To give new users a quick introduction to the software so that they can do the useful tasks xxx, yyy, and zzz after completing the tutorial. The tutorial should take no longer than 20 minutes to complete.

Sometimes there are other business objectives that are not so obvious. For example, businesses often give away a “Lite” version of their software product with a related peripheral. One business objective of that software distribution is to motivate purchases of the full product. In that context, the business objectives for the tutorial might also include:

• To explain the limits of the “Lite” version in a neutral way and to point out the advantages of upgrading to the “Gold” version. Provide instructions on how to upgrade to the “Gold” version.

Audience

Who will be using the document? Examples of audience specifications are:

• JavaScript programmers experienced in web page design
• Average users of Windows-based PCs
• OEMs trying to build a product on top of Adobe’s Creative Suite; experienced with JavaScript
• Users of the Yahoo email system

Depending on the audience, your document will differ widely in both detail and vocabulary. An installation manual designed for an elderly grandmother has to contain details that would be completely extraneous in a manual intended for a JavaScript programmer. Also consider noting who won’t be using the manual.

Technical Objectives

What knowledge should users have and what tasks should they be able to perform after reading this document? These objectives are often related to the business objectives, but are typically specified from the viewpoint of the reader. What does the reader want out of the document? For example, for a tutorial for user-level photo editing software, the technical objectives might be:

At the end of the tutorial, the user should be able to:

• Browse and open photos
• Crop photos
• Remove red eye
• Save photos, both in the original format and in a format intended for display on the web

For an API reference, the technical objectives might be:
Provide complete and accurate information on every software object and method in the public software development toolkit. Every class should list all public constructors, all public object methods and all public object variables. Every object method should include all parameters required or allowable in the method call, what the method does and what the method returns.

Focus the technical objectives on the information you are trying to pass on to the user.

Pattern of Use

How will the user interact with the document? Different documents have different patterns of use. For example, here are some common patterns of use:

• Installation manual: Read through from front to back, then never go back to it unless you need to reinstall something.
• Tutorial: Work through it once. Use it to find something that will definitely work when learning a new system.
• API reference: Use the index to find a particular item, method, or object, read about that thing, repeating the process for different objects as long as the software is in use.
• Developer’s guide: Read to understand the conceptual structure of the product before beginning serious use. Read specific chapters for mastery, as needed. Use for explanations when the reference doesn’t cover the concepts at a high enough level.

Patterns of use determine the need for indexed or cross-referenced means of entry. A reference needs an index and should have cross-references. An index is also valuable in a user’s guide that the user refers to for specific information when learning the product. Tutorials usually don’t need an index, but must flow in a logical sequence usually shown in a table of contents or an introduction.

Content

What’s in the document? This part of the spec is a rough, high-level outline of the information in the document. It’s tempting to specify the content first, but it is more productive to start with an outline and work on the content last. Documents are usually part of a document set. Typically, you put a complete explanation of a topic in one doc, and then refer to that from other documents in the set. You don’t want to duplicate information and then maintain it in multiple places.

The content that should be in the document set, as a whole, can often be specified early. The decision as to which document contains which parts of the content should be specified after all of the documents in the document set have been identified and partially specified.

Delivery Medium

How will the document be delivered to readers? Some possibilities are:

• Paper or PDF document
• Web pages
• Videos on a web server
• Help files accessed from the table of contents or an index, with no context information from the software
• Help files indexed with context-sensitive tags from the software

The delivery medium is usually specified as part of the product plan, but sometimes the specification is incomplete. For example, choices between different on-line forms are often left to the author. The delivery medium should be linked to the pattern of usage and the support infrastructure.

Example

A doc spec can be nearly any length. A very complete doc spec might be 5% to 10% of the length of the completed document. A training manual specification might include the number of training sessions to be covered, the training objectives for each session, and the type of exercises to be used in practice sessions. But even a back-of-envelope doc spec can help the customer and the writer understand the documentation plan better.

Here is a simple doc spec, for this article, the article you are reading right now:

• Business purpose: Enable fruitful discussions of document specifications between writers and customers. Improve communication on document plans and needs.
• Audience: Expert Support writers, Expert Support customers, visitors to the expertsupport.com website.
• Technical objective: Enable an experienced writer to create an ESI-style document specification; enable an ESI customer to think about doc spec issues and review draft doc specs.
• Pattern of use: Read once in detail, then reference briefly for the first few doc specs.
• Content: Intro, business purpose, audience, technical objective, pattern of use, delivery medium, content, example, wrap.
• Delivery medium: Blog post, page in the website library, PDF.

Why Doc Specs are Important

Doc specs are a means of communication between writers and customers. In any kind of work for hire—documentation or carpentry or programming—it’s important that the worker and the customer agree about what is to be produced. If there is no agreement and the work proceeds anyway, the result can be disastrous to the project and to the relationship between worker and customer. This agreement between writer and customer can come about in many ways, but a simple doc spec is easy to do and a good way to make the agreement explicit and available for discussion.

A Social Network Example

Legal briefs are documents, created by lawyers and submitted to a court, describing why the court should rule in a particular way. Both (or all) sides submit briefs on a given point and the court then rules on that point.

The movie, The Social Network, gives a fictionalized account of the birth of the company Facebook. At the end of the movie, the attorneys for Facebook decide to settle with the Winkelvoss twins. In the real life, the Winklevosses agreed to settle their claims for $20 million in cash and $45 million in Facebook stock. They later refused to go through with the settlement, and Facebook sued to force them to do so. Attorneys for the Winklevoss brothers submitted a brief to the court arguing that the settlement should be invalidated. Attorneys for Facebook submitted a brief arguing that the settlement should be enforced.

The document specification for the Facebook brief might have looked something like this:

• Business purpose: To make Winklevoss brothers go through with the settlement deal that they negotiated with Facebook in 2008.
• Audience: Federal judge and the judge’s law clerks
• Technical objective: To present the law and facts in support of the validity of the existing settlement.
• Pattern of use: Usually read sequentially. The brief should have a pyramid structure with a compelling brief summary in front, then a cogent summary of the law and facts, followed by detailed arguments on each of the points presented in the brief. The judge can read as far as needed in order to be convinced. May be read out of order, so a table of contents is needed.
• Content: Expected arguments by the plaintiff will be related to security fraud and contract law. Plaintiffs will argue that Facebook misrepresented the value of Facebook and that no meeting of the minds occurred in the settlement negotiation. The brief should focus on the information that was delivered to the plaintiffs and on their technical and financial sophistication. Pointing out that they are Harvard graduates and the children of an investment banker specializing in valuation will go a long way to counter their arguments.

Content of the actual briefs filed can be found at:
https://dealbook.nytimes.com/2011/01/13/twins-uphill-battle-with-facebook-and-zuckerberg/