Introduction

Documentation is a very important facet of any software development phase, it is a way of communication and ensurement of common understanding.

Just imagine an enterprise solution with over 40 - 50 team member working together without any proper documentation, the result may lead to failure of delivery or client dissatisfaction. However, over- documentation may lead to the same outcome as well.

No one enjoys it

Documentation is a very cumbersome task and waste a lot of effort into writing, reviewing and source controlling it.  Consequently, delivering a lot of documents with no significance may be an overhead to the project.

Documents should be as few as you can and as concise as possible. Sometimes long unreadable documentation is as helpless as no documentation at all, and I have been through both.

What to document

Everything that needs to be shared across the team, things that needs to be communicated to ensure common understanding and proper implementation. Examples may be:

• Design and Coding Guidelines written in a simple and clear format.
• Design Decisions taken, to prevent future arguments.
• Minutes of the meeting to ensure mutual understanding and to track actions.

In general document what can be very useful.  You can ask the opinion of the team to double check if any document is useful or not.

What not to document

Some other documents might not be as helpful as they may appear, like:

• Long architecture documents, just keep them simple and to the point.
• Detailed design documents, details should be entrusted in the code. Well commented code is far more helpful than long documents.

Conclusion

I have been through projects that documentation is simply for the sake of documentation, and believe me people write these ones just to get rid of the tasks assigned to them. These kind of documentation not only is a waste of time, but also were misleading to anyone reading them.

In today's business, change is inevitable and code changes regularly as well as decisions taken. Carefully select the documents that you really need and make them as simple as you can.