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 modules, the changes provided both in UI and in logic. While writing this out, the document often tends to get big (mostly 1000-4000 words - 5 to 7 pages of MS word). I make sure that nothing extra, needless or redundant points get added in the document. I also ensure proper formatting of the document for easy skimming and parsing of the reader with suitable visual aids, hyperlinks and supported citations (for further references). Still, what's required is required and I can't omit out the important details out of it.
I need to be concise but at the same time, I need to include everything that is required. And here I feel a standoff because I can't reduce the length of my document just because the end-readers feel it lengthier, and I can't keep the lengthy document because no-one would effectively read it up. How to tackle this standoff?
What I tried?
- I create powerpoint presentation to showcase the changes and notifying all the changes verbally using that powerpoint in the meeting.
- I tried to divide the internal requirements into phases and modules and for each of them, created separate documents.
What happened?
Creating powerpoint presentation and explaining stuff to team worked initially however, after a few time intervals there was nothing official on hand with us that could re-state the information/requirement. Maintaining the powerpoint was more cumbersome than the document. Plus, I had to write the document as well for official housekeeping and exchange amongst stakeholders. So it increased my time.
Some changes/features are big intrinsically and isn't possible to divide in sub-modules. So this doesn't work as well.
This post was sourced from https://writers.stackexchange.com/q/47768. It is licensed under CC BY-SA 3.0.
3 answers
"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 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/47786. It is licensed under CC BY-SA 3.0.
0 comment threads
Every propositional document (that is, one that is not telling a story) consists of three parts: the conclusion, the argument, and the evidence. The native or intuitive way that most people write such a document is to mix in bits of evidence as they develop the argument and then sprinkle bits of conclusions around as each part of the argument is concluded. The problem with this organization is that the reader has to read the whole thing even if they are only interested in parts of it.
For instance, some readers are only interested in the conclusions. For a design document, it is not their job to question the design but to implement it. They are not interested in the justification of the design or the user research data that supports the justification, they just want to know what to build.
Other people may be interested in the justification of the design decisions without wanting to dig deep into the data. They may trust that the data is what you say it is, but disagree on what to do about it. For instance, they may agree that feature X is wanted by customers but may feel it is not cost justified.
To accommodate these various reader needs, you can clearly separate out the conclusions, arguments, and evidence. There are different ways to do this that might be appropriate for different sets of audiences. For example, it is not uncommon to place most of the data in support of an argument in an appendix and just cite the top line numbers in the argument portion of the paper. It is also common to create an executive summary that just states the conclusions with only the most cursory mention of arguments or data.
There is no one template for this that is guaranteed to work in all cases. Instead, you have to figure out a design that will work for the particular set of readers you have. I call this a theory of use for the document I am about to write. The theory of use lays out my who each of the audiences is, why they are reading the document, what they are trying to do, and what information they will need to accomplish that task. If appropriate, I get the theory of use reviewed and signed off before I start work on the main document. Whether you use such a formal process or not, however, you should always have a theory of use in mind before writing any document.
0 comment threads
0 comment threads