Documentation - why and why not

by Anatoliy Biliciler on 29th July, 2013 at 9:38 PM CEST

Most of us have our own methods of working on our projects, some like to discuss every detail while some decide as they go and just like there are differing opinions on methods, there are differing opinions on documentation but what is documentation anyway? Documentation is basically fancy word for saying "Writing stuff down" and planing on paper.

For some, documentation is a waste of time because it usually ends up rarely being used (which is one of the principles of agile programming, look it up). Not to mention documentation cannot be changed on the go and leaves little room for after design changes which can mean two things: Programmer or anyone working in implementation will not be able to fix a design flaw but on the other hand programmer will have less chance to make a wrong fix and ruining the whole project.

For some others on the other hand documentation is a great tool to have. It allows you to track your progress and gives you a clearer picture of what you did ,what you are doing and what needs to be done. This documentation also allows for much efficient organization in big projects where a design team can finish their work and relay it to implementation department and work on another project then if someone does not understand a point in the document it will be much easier to remember what they are talking about.Not to mention the fact that post-op analysis can only be done right with proper documents.

image credit

One also should not forget that documents are tools and just like any tool should be properly used or it may (and probably will) backfire. There is no such thing as the more the better unless if we are talking about science and lasers. Each document you add makes the project more complicated and each bit of complexity increases chances of failure. For example an acquaintance of mine came to me to explain his project, a simple addon for phones, the first thing i asked was design documents and he came back with 64 pages of text. For some that may seem correct after all you don't want to make a mistake in the project implementation right? Well that 64 pages was mostly explanation of same mechanic over and over which could have been shown with a simple diagram. He eventually found the means to implement it and the prototype cost was almost as high as the highest bidder and all because the manufacturer confused some of the documents and it got more complicated than they could afford... all of that was because of too many pages explaining the same thing. Point in this story is, when you want to write stuff down be as efficient as possible.

image credit

In conclusion, according to professional engineers, the need for documentation depends on the size and the nature of your project, however, no matter the size of your project post-op analysis is important and demands documentation.My personal recommendation is to make some flexible design documentation for your small projects so you at least don’t forget where you left off and what you talked about.What do you think about this issue? Are you on the side of the agile or more traditional engineering? No matter which side you are on documentation is an important part of engineering and management and well… Anything!

But how much is too much and how much is too little is the question to meditate upon.


Anatoliy Biliciler ,#11 Writers Action team

Please log in or register to post a comment.

No comments.

Bookmark and Share
global youth think tank & student competition