Overview

General

This article provides tools and insights on the art of writing product specifications.

The tools provided in this document will hopefully help you to write better product specifications from this day onwards.
Choose the parts of this of this document to take with you and use them according to your taste, constrains and the standards enforced in your organization.

NOTE: The Product Specifications Document which this guide revolves around would be referred to as PSD from this point onwards.

Terminology / Abbreviations

• PRD – Product Requirements Document. See “PSD”.
• PSD – Product Specification Document. A document that details the structure, behavior and design of a product.
• MRD – Marketing Requirements Document. A document that defined the high level requirements of a future product. The MRD usually precedes a PSD document in the Product Life Cycle (from idea to product).
• SRS – Software Requirements Specifications. A document which is usually written by technical people for technical people based on a PSD document.
• STD – Software Testing Document.

Why do we need PSDs?

PSDs are mostly the result of rising organization (marketing, management, compliance, etc) needs and goals.

The first step of writing a PSD should always be the collection of the above needs into an organized list/document. We’ll refer to the collection of needs as a MRD from this point onwards.
While the MRD provides a “high-level” view of the needs, the PSD derived from the MRD should provide a “low-level”, in-depth view of the same needs along with their implications in the real world.

Preparing to write the PSD

Before you actually sit and write the PSD, make sure you have the following at hand (or mind):

MRD

The marketing requirements document discussed above. It can exist as a complete document or as notes in your head, depending on its scope/volume and the resources available to you.

Target Audience

Before writing the document you first need to realize who will be the target audience of your document and write accordingly.

Ask yourself the following questions:

• How well do they (the target audience) know the product and market? Depending on the answer you find, you’ll know the scope of the overview and terminology sections your document will require.
• How much “free” time do they have to read the document? If the target audience of your document is comprised of “extremely busy people”, you’ll find that a short and to the point document would serve all parties.
• How technically literate are they? If the readers are non-technically literate, you can either choose to simplify the technical ideas in your document or provide a rich explanation of all technical issues.
• Try and think of other relevant questions you should ask yourself before you sit down to write your PSD.

Choose an approach

There are many approaches to writing specification documents; below you’ll find examples of the most common ones. There is no “better” when it comes to the different approaches; it is all a matter of the writer’s personal taste, the nature of the product and the document’s audience.

User stories

• “User stories” is an approach usually used in Agile Software methodologies as a way to describe product features.
• User stories use an everyday language and short sentences to provide a simple “loose” description of the desired product/feature.

User stories are useful when:

• Available time for reading/writing specifications is short.
• Writers and/or readers are not technically oriented people.
• Programmers, designers and testers are trusted to make educated decisions.

Example of user stories used to define a website’s “Login” module/feature:

• A user who wishes to have a personalized experience should login to the website.
• A user needs to have a valid username and password in order to login.

A user must first register before being able to login

• A user that forgot his password can recover it via his registered email address.

User Manual

• Some people prefer to write their PSD in a User Manual format. The document describes to future users of the product how to use product and how it should react.
• User manuals tend to be very easy to read but are sometimes not technical or detailed enough since there are usually many “behind the scenes” requirements that do not fit in such a document.
• If you choose to write a user manual are your main PSD you should always include a separate, “writer’s notes” document to refer to these “behind the scenes” issues.

User Manuals are useful when:

• The product does not require much technical details.
• The target audience consists, in part, of the future users of the product described.
• You’ll eventually have to write a user’s manual anyway (save the redundant work involved).

Detailed technical document

• Detailed technical documents are the most comprehensive format for covering a product’s structure, design and functionality requests.
• The detailed technical document includes practically every detail of the product from a high level point of view down to the tiniest components (texts, icons, fields, etc).

Detailed technical documents are useful when:

• The product you define is complex and requires maximum accuracy when developing.
• The development process is outsourced and the future communication with your audience (developers, QA, etc) is limited.
• You’ll require an exact estimate of the work involved in developing the product based on your PSD.
• No further, more detailed documents (SRS, STD) will follow the writing of your document.

Important Rules

Below are a few important rules to have in mind when writing a PSD.

Consistency

One of the most important issues to have in mind when writing a PSD is to be consistent throughout the document. Lack of consistency can have severe implications on the validity of the document.

Here are some important issues you should remain constant about when writing:

• Format – Whether you choose to use User stories, User Manual or Detailed Technical formatting, make sure you keep it up throughout the document.
• Design – Colors, fonts, alignments and other styling issues. For example, if you choose to mark quotes with the following style: “This is a quote“, make sure you do so throughout the document.
• Tone – For example the way you refer to yourself: In the 1st (I will…), 2nd (We will…), 3rd body, etc.
• Names – For example, the name of a certain feature/module should remain constant throughout the document.

If you write many PSDs and your audience remains the same, constancy should span throughout all the documents you write enabling your readers to know exactly where to find what they are looking for with ease.

Atomic Writing

Atomic writing refers to a writing style in which the document is divided into the smallest possible sections (from sections through sub sections and down to bullets and sub bullets).

An atomic document has the following benefits:

• A document divided into small parts appears far less “intimidating” to the reader.
• Allows the reader to refer to each atomic part in separate which eases the reading process (for example: “See section 3.1.5″).
• Atomic parts are easier to change in case the initial needs change during the writing/reviewing process without changing the entire flow of the document.

Use Examples

Try and include as many examples as you can (all within a normal limit of course).
Examples help the reader imagine the product as a real world entity and provide well needed gaps between each information-packed section.

Finalizing the PSD

Self review

Before passing the document to its target audience, a self review is a must. Divide the review into 3 major steps:

Step #1 – High level reorganization:

• Make sure you included all the necessary material in your document.
• Make sure you have no duplicate and/or redundant issues.
• Make sure your document has a logical flow (chronological, macro to micro, etc)

Step #2 – Micro Improvements & Corrections:

• Try and break down the sections into even smaller sections (make it more atomic).
• Spell check
• Improve its appearance (styling)

Step #3 – Live Test:

• Pretend to be one of the people this document is indented for and read it. It will help you make sure the document is understandable to your readers.

Target your audience

• Create a list of all the “interest holders”. This list should include people who will develop, test, design, market and finance the product.
• Send a personal (and separate) review request to each of your audience. Sending mess email review requests tends to make sure people take this review less serious and count on the other to do the work for them.
• If possible, stress out the important parts of the document and the reasons of your review request for each of the people in your audience. For example, Programmers should be asked if the product is technologically feasible.

Tags: definitions, documentation, prd, psd, specifications