software engineering

Technical documents should be reviewed by technical people

Just recently, I was implementing a protocol at work. The protocol was handed to me in the form of a Word document and it appeared to have already cleared some approval stages. The protocol seemed over-engineered to me. It used HTTP POST with XML in the request and response bodies. There was actually only one message type and it seemed like it could have easily been implemented with a simple GET request and no response body (just an HTTP response with a proper response code). The document was 24 pages long when it only required 1. It had about 10 error response message types, about half of which had to do with XML errors. I looked at who reviewed the document and it was as follows:

  • Author: Engineering Manager
  • Reviewer: VP Engineering
  • Reviewer: Technical Director
  • Reviewer: Director of Engineering, Client Engineering
  • Reviewer: Director of Engineering, Host and Infrastructure Engineering
  • Reviewer: Engineering Manager, Quality Engineering

Missing are Principal Engineers and most importantly, Senior Developers, like myself, who will be implementing the protocol. It's not even necessary to consult the people who will be implementing the protocol, but you need to consult with people who understand HTTP, have experience with using web protocol, and an understanding of programming. One of those listed above qualifies in that respect, but that is still just one person. I am sure that if this was shown to three other people who aren't managers, directors, or VPs, they would say this protocol is over-engineered. If even one person thinks it's over-engineered, and over-engineering things is costly. It adds complexity on both sides of the protocol which means more development, more bugs, more testing. There's no excuse for over-engineering things and not excuse not to have technical documents revealed by those who will implement, the hands-on technical people.

Subscribe to RSS - software engineering