Documentation? We don't need not stinkin' Documentation!
|
|
Posted On :
Mar-13-2012
| seen (823) times |
Article Word Count :
1198
|
|
I hear it all too frequently. "Documentation takes too long" "Documentation costs too much money" "Our project is short, we don't have time for documentation"
|
|
I hear it all too frequently.
"Documentation takes too long"
"Documentation costs too much money"
"Our project is short, we don't have time for documentation"
"We're not big enough to deal with the overhead of documentation"
First, let's consider one very important thing about documentation: it is an INVESTMENT, not a cost.
What does that mean? The time you spend on documentation, if spent well, will save you more time and money than what you spend on creating the documentation.
This is true for all but the very, very small projects. And when I say small, I mean under about 10 hours.
So in short, if you put together good documentation, you SAVE yourself time and money AND the end product created is what you were expecting.
First, we need to define what it means to have "good documentation".
- Minimal - Use the smallest amount of pages having a maximal amount of information. This can be a little tricky and may take some experimentation. What usually turns people off from documentation is that they think it must be thorough and perfect. It doesn't! It should be short, sweet and to the point which means you spend less time on it and the team spends less time looking it over.
- Lots of pictures - As always, a picture paints a thousand words. On top of that, it can convey that thousand words at a glance. This reduces the amount of time people spend looking over and understanding what you wrote. And the picture doesn't need to be pretty, it needs to be simple and to the point.
- Very few words - Words take time to read. We only add text when the picture cannot quickly and clearly explain the requirements. Then we keep the text very short and usually add it as notes to the visuals created.
- Doesn't need to be fancy - You can create white board drawings, pencil and paper sketches or put it into the computer with Gliffy / Visio
- Must make sense to a person other than the one who wrote the
- Follow industry standards that the team understands
When building software, the minimum documentation you needs is:
- Data diagram - This is an absolute must for the developer and also helps to ensure a great firm foundation for your software project. Whether in memory or in a database, your data is the foundation of your application. Without a firm foundation the software will fall down like a building built on a sink hole.
- Screen flows - This diagram gives you a full inventory of all screens in your application and how each one flows into the next. We also like to include brief notes about the business logic as you go through the system. This reduces how many pages of documentation you have and increases how much information you can pack into each page.
- Mock-Ups - Mock-ups show what is on each screen, how it lays out and has brief notes on what kind of validation and user interaction may occur. Developers often work from one screen to the next and having the notes right there on the drawing of the screen helps ensure they don't miss important functionality as they build.
Additional optional documentation:
- Sample data - This is great in spreadsheet format. Sample data quickly shows a developer what to expect. From user input to data output, having sample data reduces build time and gives real concrete data for the developer to test with which reduces bugs and time spent debugging the system.
- Test cases - Test cases lay out what a user with do in the system, what they will enter in and how the system should respond. You should only supply test cases when there are special cases a developer and test may not consider or when the functionality of that part of general database application development is complex.
- Process flow diagram - Usually your screen flows are enough but sometimes there is an overall process as duties are handed from one person to the next that are not visually demonstrated in the screen flows.
What documentation buys you:
- Saves you time having to communicate with the team about what you want so you can hand the work off and get back to your job.
- Gives you a visual of what the final application will do. This aids in usability testing and finding potential problems with how the system flows before you sink a lot of time into the build of an application that has design flaws. It also illicits better feedback from users so design changes can be made before development moves in the wrong direction.
- Helps the development team dive in and start coding. The developers spend very little time scratching their heads and wondering what you meant. The development moves quickly and smoothly. Without documentation the developers have to spend a lot of time thinking about what to do or have to frequently stop and ask for clarity which slows them and the whole project down.
- Increases the success rate by ensuring the application built is what you expected.
- You are not truck sensitive - if someone leaves, you have the knowledge in the documentation so new team members can get up to speed on the project quickly and easily which saves you time and money in the long run.
Most people just hate putting together documentation. They find it boring and tedious. They would instead rather just jump in and start working furiously. It feels like they are getting things done. In reality they are spending much longer than they should and the products they deliver are not as accurate to the vision of the client as they could be. This leads to longer development times and higher costs, whether it’s Java Development or Web Application Development.
What we promote is a healthy balance between these two extremes: writing the least amount of documentation to convey the greatest amount of information. On small 1 - 2 week projects, the documentation may only take an hour or two to assemble. It isn't hard to save an hour or two just in not having to shoot emails back and forth and avoid meetings to clarify what we want. Typically the investment of time in the documentation is between 2% and 10% of the time of the build. I commonly see this save 25% to 50% on the build itself. The savings can be very big, even on small projects.
So before you start your next project, ask yourself, do you want to turn your back on savings? Do you want to take more time getting it done? Do you want the final product to be less than you were hoping it could be? If so, skip the documentation.
But if you want it done faster, better and at a lower cost, get that simple, minimalist documentation together.
|
|
|
|
Article Source :
http://www.articleseen.com/Article_Documentation? We don't need not stinkin' Documentation!_162619.aspx
|
|
Author Resource :
If you would like help getting the biggest bang for your buck for Android development or any development, let us know. We would love to help!
|
|
Keywords :
Android development, Java Development, Web Application Development, database application development,
Category :
Computers
:
Software
|
|
|
|
