I was recently discussing with a group of fellow developers the qualify of documents which are usually done to list the product requirements. After complaining about the low quality of most documents I've seen (and this complaint was shared by the other persons), I ended up talking about two specification documents which, in my eyes, were unusually good at their job: the documents I wrote for two projects a few years ago. Recalling the discussion later, I thought it would be interesting to bring more light on those two documents, and what made them special.
The first one was a small project which was abandoned a few months after I started working on it because of the lack of interest. The document I wrote was an excellent example of formal methods of requirements writing. The project was born during the period of time where I was reading James Taylor's Managing Information Technology Projects and similar books, and I was convinced that formal requirements elucidation is the best way to do the job. It looks naive, in retrospective, but I had my reasons to believe it back then: the methodology was well known and well documented, and could probably be beneficial for many projects, if only business analysts would take any interest in those approaches.
Given the small size of the project, the requirements document contained no more than fifty pages. After a short description of the project itself, the document actually listed, in a very formal way, every functional and nonfunctional requirement I could think of. This formalism, by the way, helped me later to have a good grasp on non-functional requirements most developers seem to lack.
When working on the project itself, I was really proud of my work on requirements: everything was clear and well organized and complete. Surprisingly, it appeared that I haven't missed a lot of aspects of the system, including the non-functional ones--if I had to do the work again today, I would miss at least half of the things. A few features appeared different than I originally thought, but keeping the requirements document up to date wasn't difficult at all.
It could be perfect, unless one thinks about the actual usage. It appeared that I was both the business analyst and the developer. It was my system. I had to decide every aspect of it, and I had the overall view of the system in every detail. In real world, it doesn't work this way. Business rules are drafted by one guy, who is (hopefully) knowledgeable about the business domain, but has usually no clue about the technical aspects. Technical rules are drafted by another guy, who may call himself an architect and claim to have dozens of years of experience in IT, but who don't necessarily code on daily basis. And finally, the document is thrown to a bunch of guys who love their programming language and their IDE, but have no idea what the document is about, and don't necessarily want to read technical stuff. What makes things worse is that usually neither the business analyst, nor the architect, nor the developers know the formal approaches for writing requirements, and even if one of them appear to know this stuff, the others don't, and couldn't care less.
This situation leads, obviously, to the usual result we all know: the document which, even when it is well done, is not read or understood by the persons who actually create the software product. This is an unfortunate fate of any formal requirements document: if the requirements step succeeded for the first project, it's only because my case was very specific. It couldn't be used as a valid illustration of a technique which works.
The second project used a different approach. There was absolutely no formalism, and it wasn't even looking as a requirements document. There were no lists, and no numbers, and no cross-references. Instead, there was plain text, a narrative.
The document started by giving an overall view of the system. It was a product which was a combination of two smaller systems interacting with each other. Anyone who have read the first few pages had a very clear, but also not very detailed view of the system, and could explain the purpose of it.
Every successive part of the narrative entered in more and more details. In order to work on a specific part of the system, one could read the specific part of the document, and there is was, all the information needed to understand this part in enough detail, and with enough abstraction from other parts. The different sections were written in a way that made them autonomous: no exhausting cross-references, but rather a plain explanation of all the details one needed.
In software industry, communication issues represent a major issue. Many persons in corporate world don't write and don't read. While it is usually the task they are expected to do most of their time, they find it not that important, and often don't spend enough time doing it correctly. They don't read their emails in detail, and they often make no effort when it comes to writing.
The direct effect is the extreme loss of performance due to the lack of proper communication skills. Talking about requirements, most content I receive from some customers is usually unreadable. Being unable to formulate the most basic ideas, those persons don't even make efforts communicating: they simply draft stuff without even reading it before dispatching it. How many times I found myself reading some paper describing a feature of a project, trying to get at least a slightest idea about the thing, and discovering later when discussing the subject with the author that what I imagined has absolutely nothing in common with the actual feature!
Now, I believe that it's not the fault of those persons that they communicate so poorly. The culprits are the medium, the habits, the culture, and imitation of existing corporate emails, documentation, requirements documents and any technical documentation.
Now change the context. Tell the person that she should write a story, a book, a novel. The focus is shifted from imitating other poorly written documentation to imitating actual authors and real books. While not every book is equal, book authors write still slightly better than an average business analyst who creates the list of requirements. The better the reference to imitate, the better is the result.
This doesn't mean that every business analyst is able to write properly and clearly only by changing the style of the document. What this means, on the other hand, is that through the shift in references, the average level could only improve.
Technical documentation is usually boring to read. The practice is very different from reading a novel: instead of following the narrator, one has to jump through cross-references, losing one's track, going back, reading again, trying to establish links which were missed by the author, and trying to keep the whole picture in all its details in one's head.
But it doesn't have to be boring. Or, if it is boring, it doesn't have to be written in the first place. Why would you write something nobody would read? Or the ones who will be forced to read it, will suffer? It doesn't make sense.
If, on the other hand, the documentation is written as a novel, more people could enjoy reading it. And sharing it as well. Once the document is read and shared, it is also maintained. What could be more unfortunate than spending time on a document nobody reads, and which gets outdated very quickly anyway?
A list of requirements, as usually presented, has a structural flaw: it is linear. What I mean is that all requirements are at the same level and are expected to be very granular. This granularity is problematic on any ordinary project: going down to every detail is not very different from simply writing source code directly.
Adopting the narrative style helps staying close to the actual process of requirements elucidation. One starts by getting an overall view, and then adds details, obtaining a high granularity on the parts which seem clear at the moment of writing, and remaining superficial on parts which look too vague at the early stage. This very difference between parts described in detail and parts which are not is an essential reflection of any business project.
This makes it also possible to let the developers fill the gaps. When the business analyst or, more probably, the architect, cannot describe every detail, developers may adapt their implementations and eventually get creative, which is exactly what one should expect from them.