The documentation is the spec

A prob­lem en­coun­tered by most de­vel­op­ers and teams is that any pro­ject re­quires to per­form a lot of tasks in par­al­lel. Writ­ing code im­plies do­ing a bit of de­sign, refac­tor­ing should be done at the same time, but there is also test­ing, and doc­u­men­ta­tion, and re­quire­ments, and... well, you get the pic­ture. Be­gin­ners can eas­i­ly be de­pressed by the num­ber of tasks to do, and end up with no test­ing or no doc­u­men­ta­tion or no de­sign.

An­oth­er de­press­ing as­pect is re­dun­dan­cy. We learn that du­pli­ca­tion, would it be data du­pli­ca­tion or code du­pli­ca­tion, was in­vent­ed by the dev­il and is an ac­tu­al hell for DBAs and main­tain­ers. At the same time, the busi­ness log­ic is du­pli­cat­ed be­tween code, unit tests and ac­cep­tance tests, and doc­u­men­ta­tion and re­quire­ments look pret­ty sim­i­lar.

But isn't this sim­i­lar­i­ty a sign that du­pli­ca­tion could be avoid­ed?

It looks like it could, and it is, and while the idea is not as pop­u­lar as it should be, it ac­tu­al­ly pro­duces pos­i­tive re­sults in many pro­jects.

Take re­quire­ments and doc­u­men­ta­tion, and more specif­i­cal­ly the end-user doc­u­men­ta­tion of an API.

• Is there some­thing which should be in­clud­ed in the doc­u­men­ta­tion with­out be­ing in the spec? Prob­a­bly not: if you are doc­u­ment­ing a be­hav­ior which is not de­scribed in SRS, your SRS is in­com­plete. For in­stance, a range of ac­cept­ed in­put val­ues, doc­u­ment­ed for a giv­en API ac­tion, should also be in SRS.

• Is there some­thing which should be in­clud­ed in the re­quire­ments with­out be­ing in the doc­u­men­ta­tion? Yes, the rel­e­vant in­ter­nals, such as every non-func­tion­al re­quire­ment of per­for­mance. But what if we take in con­sid­er­a­tion not only the end-user doc­u­men­ta­tion, but also the in­ter­nal one?

Work­ing on Iris, the pub­lic doc­u­men­ta­tion is ac­tu­al­ly the spec. I wrote the doc­u­men­ta­tion pri­or to the de­vel­op­ment of the API, and up­date it on reg­u­lar ba­sis when im­ple­men­ta­tion de­tails in­di­cate that the spec... sor­ry, the doc­u­men­ta­tion is in­com­plete. I did a bad job of doc­u­ment­ing every as­pect of the API, but if I did, it would be a damn good spec by it­self.

This also shows a flaw in many cor­po­rate pro­jects. They start with a draft of the SRS (which usu­al­ly takes a form of dozens or hun­dreds of pages of un­read­able crap no­body uses be­cause of dis­gust), then the pro­ject is im­ple­ment­ed, and fi­nal­ly doc­u­men­ta­tion is writ­ten. But why? What if we doc­u­ment the pro­ject be­fore im­ple­ment­ing it?

Iris showed an in­ter­est­ing (and com­mon) pat­tern. I draft­ed a few things on pa­per be­fore start­ing the pro­ject: not much, just two pages of di­a­grams and gen­er­al con­cepts.

Then I wrote the doc­u­men­ta­tion, and found that my pri­or draft­ing was not only in­com­plete, but also par­tial­ly wrong. The term “in­com­plete” is key here. It means that the doc­u­men­ta­tion ac­tu­al­ly helped think­ing about the dif­fer­ent as­pects and de­tails of the pro­ject.

Then, I start­ed both the im­ple­men­ta­tion of the pro­ject it­self, and the client side, that is the part of a dif­fer­ent pro­ject where the API is ac­tu­al­ly used and trans­lat­ed into pret­ty im­ages, nice round­ed but­tons and oth­er UI stuff. Sur­pris­ing­ly, it's not the im­ple­men­ta­tion, but the us­age which re­vealed a few oth­er as­pects I missed when draft­ing the doc­u­men­ta­tion (that's why eat­ing your own dog food is es­sen­tial).

The es­sen­tial dif­fer­ence, I think, is that doc­u­men­ta­tion in­volves high­er re­spon­si­bil­i­ty. When peo­ple write the spec, they have in mind that the spec will be read by only few peo­ple. There­fore, they won't take nec­es­sary ef­forts to think about it and to write it well, which in turn makes it too dis­gust­ing to be used by any­one. On the oth­er hand, doc­u­men­ta­tion re­quires care, and this sense of do­ing some­thing im­por­tant which re­al­ly mat­ters may en­cour­age to think about the de­tails and to write well.

This works per­fect­ly for APIs. I haven't test­ed it for desk­top ap­pli­ca­tions, but I have an im­pres­sion that it will work too. Have you? Was it suc­cess­ful?