Documentation we don't need not stinkin' documentation!
Documentation? We dont need not stinkin Documentation!I hear it all too frequently. "Documentation takes too long" "Documentation costs too much money" "Our project is short, we dont have time for documentation" "Were not big enough to deal with the overhead of documentation"First, lets 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 saveyou 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 underabout 10 hours.So in short, if you put together good documentation, you SAVE yourself time and moneyAND 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 peopleoff from documentation is that they think it must be thorough and perfect. It doesnt! Itshould be short, sweet and to the point which means you spend less time on it and theteam spends less time looking it over.* Lots of pictures - As always, a picture paints a thousand words. On top of that, it canconvey that thousand words at a glance. This reduces the amount of time people spendlooking over and understanding what you wrote. And the picture doesnt need to bepretty, it needs to be simple and to the point.* Very few words - Words take time to read. We only add text when the picture cannotquickly and clearly explain the requirements. Then we keep the text very short andusually add it as notes to the visuals created.* Doesnt need to be fancy - You can create white board drawings, pencil and papersketches or put it into the computer with Gliffy / Visio. We usually start by sketching outon a white board while discussing the requirements with the client. This speeds up thediscussion (less time spent defining the project) and then just take pictures with our
phone. Wow, documentation without having to spend additional time documenting! Weformalize in the computer only when the project is large or we feel it will start saving timeso we dont have to redraw things because of little tweaks.* Must make sense to a person other than the one who wrote the documentation -Before unleashing the build team, run the documentation by everyone on the teamincluding the developer, end user and client. This will help you find flaws in the designbefore sinking time and money into building something that wont work. It also helps youfill in the information you may have forgotten.* Follow industry standards that the team understands - Use notation, vocabulary,drawing and symbols that are common place. This will help reduce the time you have tospend explaining to people what you mean in the documentation. It will also helpeveryone speak the same language when communicating about the project whicheliminates confusion.Good documentation should be something you can put together quickly and easily. Itshould be something your team easily understands. And it needs to answer at least 90%of the questions you typically have during the build of the project.When building software, the minimum documentation you needs is:* Data diagram - This is an absolute must for the developer and also helps to ensure agreat 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 softwarewill fall down like a building built on a sink hole.* Screen flows - This diagram gives you a full inventory of all screens in your applicationand how each one flows into the next. We also like to include brief notes about thebusiness logic as you go through the system. This reduces how many pages ofdocumentation you have and increases how much information you can pack into eachpage.* Mock-Ups - Mock-ups show what is on each screen, how it lays out and has brief noteson what kind of validation and user interaction may occur. Developers often work fromone screen to the next and having the notes right there on the drawing of the screen helpsensure they dont miss important functionality as they build.Additional optional documentation:* Sample data - This is great in spreadsheet format. Sample data quickly shows adeveloper what to expect. From user input to data output, having sample data reducesbuild time and gives real concrete data for the developer to test with which reduces bugsand 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. It includes both normal situations as well aswhen the user interacts with the system incorrectly. We have to be careful with this one.All too often people preparing documentation go a little overboard here and try to add atest case for everything. You should only supply test cases when there are specialcases a developer and test may not consider or when the functionality of that part ofgeneraldatabase application development is complex.* Process flow diagram - Usually your screen flows are enough but sometimes there isan overall process as duties are handed from one person to the next that are not visuallydemonstrated in the screen flows. An addition of a process flow diagram helpsdevelopers and testers see how the system is actually going to be used. We typicallyuse an industry standard process flow diagram or swim lines.What documentation buys you: * Saves you time having to communicate with the team about what you want so youcan hand the work off and get back to your job and not have to micro-manage the project.* Gives you a visual of what the final application will do. This aids in usability testingand finding potential problems with how the system flows before you sink a lot of time intothe build of an application that has design flaws. It also illicits better feedback from usersso design changes can be made before development moves in the wrong direction.* Helps the development team dive in and start coding. The developers spend verylittle time scratching their heads and wondering what you meant. The developmentmoves quickly and smoothly. Without documentation the developers have to spend a lotof time thinking about what to do or have to frequently stop and ask for clarity which slowsthem 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 thedocumentation so new team members can get up to speed on the project quickly andeasily 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 aregetting things done. In reality they are spending much longer than they should and theproducts they deliver are not as accurate to the vision of the client as they could be. Thisleads to longer development times and higher costs, whether it’s Java Development orWeb Application Development.But most people dont see this added cost of time and money. Why not? Because theydont try it both ways to see what works.Also, most people think documentation means writing a book. They prefer writing no
documentation (one extreme) as opposed to writing 100+ pages of detailed specifications(the opposite extreme).What we promote is a healthy balance between these two extremes: writing the leastamount of documentation to convey the greatest amount of information. On small 1 - 2week projects, the documentation may only take an hour or two to assemble. It isnt hardto save an hour or two just in not having to shoot emails back and forth and avoidmeetings to clarify what we want. Typically the investment of time in the documentationis 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 onsavings? Do you want to take more time getting it done? Do you want the final productto 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, minimalistdocumentation together.And if you would like help getting the biggest bang for your buck for Android developmentor any development, let us know. We would love to help!