Thursday, October 25, 2018

About reading a formal specification document

Recently working with the DMN specifications for FEEL, I have come to better understand how a team should better approach the "reading exercise". So here are a few thoughts on how to read and what to expect, and what you may need.

1. Sans solo


You'll definitely go mad reading it alone. But the main point is, you can read it alone, but record your interpretations in the form of margin notes, or, example. So yes, its always better to keep a hard copy and read it. The notes can be small, but something concise that captures your thought at that point of time.

2. What is life, but a myriad of interpretations


When multiple people read the specs there is bound to be multiple interpretations. This is a good thing as long as its peaceful. But sharing those interpretations with your colleague or boss is a good thing. This way you can iterate through difficult sections of the specifications document, and resolve ambiguities.

3. There is always a community behind the specifications document


So its a good idea to use the internet and try to reach out to one such community. Because, sometimes, crowd-sourcing is good. Now you may not always hit the right idea, but, it opens up people to your interpretations. And sharing your interpretations is a good thing.

Chances are the community you are trying to be a part of might be really small. You may be under a deadline to understand a document, and, help doesn't come quickly. Expect the worst, but do share your thoughts, nonetheless.

4. Too many cooks are good here


Usually its always the developer reading the document. (Or developers). And his/her interpretations are "developer-ish". Perhaps its more focused towards implementation. Avoid this as much as you can. There should be a sales person, there should be a project manager, a very patient end stakeholder, etc involved in the reading exercise. They all will have their own interpretations. Some of them may be incorrect; some of them may be short-sighted. The mantra is share your ideas none the less, discuss, and, come up with the correct idea.

5. At least one right cook


Its always better to have a subject matter involved in the exercise. In most cases, one such person is absent. Then this advise is really not of much use to you. But if there is one such person, fish him out. It will only help.

So here are some thoughts I could write under 30 minutes. If you do have any you can share your two cents too.