: Re: 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

@Goswami879

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)

Login to post a comment!