: 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

@Hamaas631

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)

Login to post a comment!