The importance of documentation

After reading TOS Chapter 8, I've found a few things most interesting and important:

1.  Importance of code commenting.  Commenting doesn't just help me understand what's happening when I go back through the code months later.  More importantly, it helps others who may look at this code have an idea where to start when looking over the code.  Employers are probably most interested in programmers that practice detailed commenting, because it helps the company progress further faster in the long run.

2.  Importance of technical writing.  In my experience thus far, I've already created up to 80 page long documents that go into detail about designing software, and I have an idea of how important it is to keep these documents living.  When going into the process of actually implementing the software, the documentation is a great place for me to look back onto, just to make sure I'm following the "plan".  With thorough documentation, you can think deeply about issues that may arise during the implementation process.  This helps you plan again against any possible issues, and helps make the implementation process less painful and straight-forward.

3.  Keeping documents updated.  It's very important to keep a document "living", following the "waterfall" method.  If you've completed a document and have gone onto implementation, there will most likely be changes in implementation that weren't accounted for at the documentation stage.  It is important to document these changes, so that the next person who comes along can still follow the documentation.  Otherwise, comparing documentation and the actual implementation may appear confusing to a newcomer.

4.  Collaborating on documentation.  Having more than one person work on the same document can prove very useful.  Almost like "pair programming", when two people get together and discuss a design for a software project, it helps create a broader view of how the software will work.  Having a detailed discussion about a project will help the designers think more deeply about what needs to happen -- which helps prevent issues in the long run.

For our project, we will absolutely be creating some detailed documentation for our design.  I know that in the long run, it will prove to be very useful and help us save time.