: How to eliminate standoff between "Lengthy" vs "Concision"? Often while writing a software requirement/change-request documentation, I need to include the quoted requirements descriptively, the impacted

Vote Up Vote Down

The Comprehensive Rules of Magic is a reference document that holds all of the rules and possible corner cases found in Magic. It is NOT meant to be read beginning to end; instead it's meant to be consulted when specific rules questions come into play.

Forward to the Magic: The Gathering Comprehensive Rules

Some documents are designed to be read, others are designed to be referenced

It sounds to me like you are creating a reference document. That means you are documenting every requirement to the highest level of detail possible. It doesn't matter how long a reference document is, because nobody will be ever reading the entire thing. Instead what matters is how quickly the users can find the specific information they are looking for.

This means a robust Table of Contents, with a fairly granular subdivisions.

Don't be afraid to take up space. It doesn't matter if your document is 100 pages long, as long as the user can jump to page 37 in a second from the table of contents, and have it be the page that they need. It's easier to find information is bulleted lists of short sentences than in dense paragraphs - space out your information where you can.

The MtG Comprehensive Rules I mentioned above are 125,000 words long, but most sections aren't more than a couple of lines long, so looking up a needed rule rarely takes a significant length of time.

In addition to your reference document, create an overview document

A reference document is only useful if the users know what they want to look up. So you should create a companion document which is designed to provide a summary of the requirements that you are explaining. This document prioritizes readability and conciseness over completeness and accuracy. It provides the context and clarity needed to understand the structure of the reference document.

Ideally, someone brand new to the project should be able to read the overview document and be able to follow along at a meeting using only the information gleaned there.

(0)

Vote Up Vote Down

"Concise" doesn't mean "very short"; it means "no more verbose than it needs to be". In your case, you have needs that establish a minimum length. Trying to fight against that will only lead to frustration, as you've seen. If people are using this document as a basis for implementation, it's better to have all the requirements in one document instead of splitting it up and taking the chance that someone will miss some of them.

But you can still create the feel of a concise document, even if the required contents mean it's a longer actual document than you wanted. The keys to this are structure and navigation -- make it easy for the reader to get to the exact part that's needed right now, and make each part concise but complete.

I'll illustrate with API reference documentation because I do a lot of that. (I'll get back to your use case.) Each topic addresses one code element (for example, a class). Topics use a standard structure -- short text description at the top, code interface for the functions in this class, alphabetical list of functions with their full specifications (parameters, return values, preconditions, description of what it actually does, etc), and optionally a section of examples. A reader who's looking for the specification of function X on class Y knows exactly where to go. A reader who wants to browse to see what's available knows it's ok (at the moment) to skip the detail sections. A reader who basically knows how it works can jump to the bottom and then scroll up to the beginning of the examples.

You've mentioned two types of requirements (UI and logic). I'll bet you have a couple more categories (performance, environment/dependencies, maybe others). The reader who's focused on the UI wants to be able to jump to those and skim the rest. The reader who's focused on what your system is going to do to the back-end servers wants to look at performance and dependencies and might not care at all about the UI. The reader who is responsible for evaluating the requirements against use cases cares about coverage and needs to read almost everything.

Group your requirements by type (it sounds like you already do), and use the same order in all of your requirements documents. When requirements interact, cross-reference them -- you might need to make individual requirements linkable or you might be able to do it by subsections within your sections, depending on your domain and level of granularity. Link to supporting documents like use cases where applicable. Provide a table of contents at the beginning so people can easily jump to the sections of interest. If using a paging layout (Word, PDF) instead of a scrolling layout (HTML), start each section on a new page to make it easier for people to page through the document.

Some requirements documents provide an overview or executive summary of a few paragraphs at the beginning. In my opinion it's more useful to put a summary of a paragraph or so at the beginning of each section, so all the UI stuff is together, all the backend stuff is together, all the performance stuff is together, and so on. Either approach can work, though, so see what your readers prefer.

(0)

Vote Up Vote Down

It sounds like there may be more than one audience for your documentation, and the struggle you're having is trying to optimize your output(s) to appease as many as possible. Furthermore, it sounds like you know this is the issue, since you have tried differing strategies to reach those goals.

To tackle the stand-off you might just have to be willing to cut the Gordian knot: stop trying please everyone. It's just not a good use of your time and talents.

An executive summary has its place. An overview of changes and their relations to the road-map are necessary for team effort to be optimized. But at a certain point you are throwing effort into a job that the reader themselves should be doing. (Taking a big step back: If you are required to output volumes of documentation that no-one reads because they don't have time to do so, then this is a management issue.)

(0)