This entry is about my execution as a newbie at creating documentation for a computer system. A story that will let you know what happened the first time I delivered a document for a final revision to the end user, which unfortunately, left no room for doubt that I was a beginner.
This happened in 2005, the year I finished my studies as a Computer Systems Engineer, and when I was first invited to participate in a software development project for real.
This project was my formal introduction to the life of a software developer. We were three people working on the project doing every task required from us: analysis, documentation, system administration, database specialist, graphic design, testing, and whatnot.
For the documentation part, we were asked to create an SRS (Software Requirements Specification) document, unknown to me from my school days. I also came to realize that contrary to what happened during my Engineering student life, I actually enjoyed making technical documentation.
During the first three weeks of the project we were analyzing the software requirements, created use cases, and documented every other particular aspect of the soon-to-be new system. One week later we had the first version of the SRS ready for review, with each section of the document according to a template handed to us, a context diagram that fully explained the interaction between the system and other platforms. To me, it was a perfect product, my firstborn baby, the result of extreme caution during the documentation phase. The last part of the analysis phase was to get the end user’s approval.
We delivered the SRS for review on a Wednesday morning. Mario, our end user, would check it last and would give us his feedback. He was a very (very) busy man, always occupied, going back and forth to and from his office several times during the day, even greeting him was a challenge, For some reason, almost every review meeting would take place in the evening, he would let us know that using his trademark phrase (later used as our own): “Would you mind reviewing this after lunch?”
At 4:30 pm, we were sitting at Mario’s office waiting for his feedback. No major comments on the document. According to him, the document described quite well the business rules and the expected result. He wanted us to make a few amendments to specific sections of the text, though.
“Third sheet, second paragraph. State that the web portal should be available 7×24”
“Fifth sheet, below the diagram. State that the task is performed by Management”
Page after page, very small changes were asked. When we passed the 20th sheet of a round total of 64, the review was still going on the pace slowed down. Mario was referring to paragraphs giving us some hints to identify them, like the starting words or the location on the page. He was going back and forth, page after page without telling us to move forward or backward on our copy. Then, the moment of terror and the source of this story came to be:
“Go to the page where it reads <<the execution of the stored procedure…>>”
“What page is that?” – I asked.
“I really would like to tell you that, but you gave me a document with no page numbers and without a table of contents“
That phrase is still in my head, 20 years later (and counting).
That was the first and last time I delivered a document like that.
That same evening, Mario had a new version of the document to review, with the requested amendments, beautiful page numbers at the bottom right corner of each page, and a marvelous table of contents following the front page.
“Would you mind taking a look at this story after lunch?”
Deja un comentario