Agile Attitudes- Agile Documentation
agileattitudes at agilerules.com
agileattitudes at agilerules.com
Sat Nov 20 16:13:00 EST 2004
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 at agilerules.com - PLEASE put "RSVP" in subject line
email to nancyv at 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 at agilerules.com.
O><O><O><O><O><O
Your feedback is welcome! Send feedback to info at 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 at 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.
--
-----------------------------------------------------------------------
Nancy Van Schooenderwoert Agile Rules
nancyv at agilerules.com http://www.agilerules.com
-----------------------------------------------------------------------
More information about the AgileAttitudes
mailing list