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.

Comments

Much obliged to you again for all the information you distribute,Good post. I was exceptionally keen on the article, it's very motivating I ought to concede. I like going to you site since I generally go over intriguing articles like this one.Great Job, I incredibly acknowledge that.Do Keep sharing! Respects, packers and movers in pune

I genuinely thank you for the vital data on this phenomenal subject and suspect more wonderful posts. Thankful for getting a charge out of this gloriousness article with assignment writing services UK. I am inviting it all that much! Expecting another exceptional article.

Thanks a lot for your great article, its true, technical; documents should always be reviewed by technical people. People make mistakes when they do not take this aspect into consideration.I am a researcher with essay help as a researcher and this article is just interesting...

I’ve been surfing online more than three hours today, yet I never found any interesting article like yours. It’s pretty worth enough for me. In my opinion, if all webmasters and bloggers made good content as you did, the web will be a lot more useful than ever before.
womens designer shoes

my english instructor doled out us to compose a "specialized document"says its not a "how to" but rather cohorts assume of it that way.. im not precisely beyond any doubt how to Writing dissertation services | dissertationboss compose it.. so exhort or direction on that would be useful. however, i basically require help choosing what to compose mine on... recommendations?! due soon. need to begin FAST :] tnx! btw. im in eighth grade xD

Thank you so much for the post you do. I like your post and all you share with us is up to date and quite informative, i would like to bookmark the page so i can come here again to read you, as you have done a wonderful job.
baby stroller

An entrancing dialog is quality remark. I surmise that it is best to compose additional on this matter, it won't be an unthinkable point however for the most part individuals are insufficient to chat on such themes. To the following. Salud Josh Greenly

It’s an important point to consider that “Technical documents should be reviewed by technical people.” There is no better option available for the task than the seeking help from a professional in this field to get a better result. Paris attraction tours

Add new comment