AgileAttitudes Article
 
 
 

Vol 01 Issue 12- Agile Documentation

  
 
Back to the list of articles Agile Attitudes Volume 1, Issue 12 Nov. 20, 2004 A free bi-weekly email newsletter Brought to you by Agile Rules consulting www.agilerules.com ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Welcome to Agile Attitudes, a newsletter of ideas, insights and technical tips that help people find better ways to develop software. Feel free to share this with anyone - just be sure you send or print the whole thing, including the copyright notice. Directions for managing your subscription are below. O><O><O><O><O><O New England Agile Bazaar hosts A L I S T A I R C O C K B U R N Location: Mitre Corp., Bedford MA, Auditorium in S bldg When: 6:00 - 8:30 pm, Dec 9, 2004 Cost: $10.00 per person, cash only. RSVP is necessary RSVP: to nancyv@agilerules.com - PLEASE put "RSVP" in subject line email to nancyv@agilerules.com for details, directions, etc. O><O><O><O><O><O Agile Documentation by Nancy Van Schooenderwoert I was surprised to find that an audience of software engineers wanted to know about documentation techniques. At a recent conference, I was giving a talk about my experience using extreme programming for embedded software applications. As part of that talk, I listed a number of areas where I could go into more depth - including "agile documentation". That was one of the top things they wanted to know more about. Documents created as part of a software project can be classed into these categories: * Useful for future maintenance of the system * Needed for supporting end-users * Supports ongoing management of the development effort * Records software architectural decisions, and high level design * Helps developers get the job done (checklists, diagrams, overviews of complex interactions, etc.) At any point in time, there is a "right amount" of documentation which can facilitate the work. Too little documentation, and people are inefficient; too much and they're distracted from the main task by the burden of maintaining the documents. The key is to recognize that creating "tested, working code" is job number one. Any document (prose, checklist, graphical model, etc.) that helps those doing the work is appropriate, and is agile documentation. Some documents exist to convince management that the project is under control, or that the team correctly understands what to build. But there is something that can do that job much better than a document - tested, working code! The whole point of an agile project is to start delivering functionality as soon as possible so the customers can give feedback to the team. When tested, working code is delivered early and often, everyone in the project team starts to focus on the work itself, rather than talking (and writing) about the work. This isn't to say that design documents shouldn't be created. Rather than aim for a completely detailed design document, it's more practical to create just enough design so that the implementers see what to build and deliver first, and how that will fit into the overall product. If the product is a nuclear submarine, quite a lot of design needs to happen early. If it's a web application to organize the family photos, then a quick diagram is fine. Status reports, spec documents, etc. may need far less in them (if they must exist at all) when you've got automated unit tests, acceptance tests, and the various "information radiators" that agile teams use. At every point in time, before creating any document you should ask: * Who needs to use this information? * Do they need it now? (Or just part of it now?) * Have we asked the intended users of this document what they need? * Would it be better to write this document when the product is more stable, and just collect together some of its content as we go along? * If developers will write this, is this more important than having them write software? Should a tech writer collaborate with them? Agile documentation is a big topic. For a more detailed look, see Scott Ambler's essay here: http://www.agilemodeling.com/essays/agileDocumentation.htm O><O><O><O><O><O More articles on Agile software topics at http://www.agilerules.com Within our company we have a sub-specialty in embedded systems. Our site has articles on embedded XP and we support a discussion list focused on the use of agile methods for building embedded software. The list signup info is at http://www.agilerules.com/mailinglists.phtml O><O><O><O><O><O To help you get started with in-depth research into Agile Attitudes topics, we have added a Library section to our web site at http://www.agilerules.com/library.phtml Order using our links and receive discounts up to 30%! O><O><O><O><O><O If you enjoyed this issue or found it useful, forward it to a friend! Help spread the word about better ways to build software. Invite your friends and colleagues to join our growing reader community at http://www.agilerules.com/mailinglists.phtml O><O><O><O><O><O Looking for a speaker for your next corporate or society meeting? We present dynamic, informative programs on topics of interest to managers and technical staff in their transition to more flexible, robust ways to create software. O><O><O><O><O><O Want to reprint this issue in your company or society newsletter? For permission to reprint any of the articles, contact us at info@agilerules.com. O><O><O><O><O><O Your feedback is welcome! Send feedback to info@agilerules.com To manage your subscription: http://www.agilerules.com/mailman/listinfo/agileattitudes O><O><O><O><O><O Brought to you by Agile Rules consulting 162 Marrett Road, Lexington MA 02421 Copyright (c) 2004 Agile Rules info@agilerules.com O><O><O><O><O><O Privacy notice: We will not release a subscriber's address to any third party for any reason. This is a strictly opt-in newsletter. No one is ever subscribed without their explicit request. _______________________________________________ AgileAttitudes mailing list AgileAttitudes@agilerules.com http://www.agilerules.com/mailman/listinfo/agileattitudes </plaintext> </td id="bodytable_r1_c3_body"> </tr id="bodytable_r1"> </table id="bodytable">