On Documentation
In my book: Agile Software Development: Principles, Patterns, and Practices, I describe "Martin's first law of documentation" as: Produce no document unless it's need is immediate and significant. Some folks have taken this to mean that Agile Development is development without documentation. This is not the case.Documentation is a necessary part of all software development projects. Rejecting documentation in the name of "Agility" is a flawed religious behavior. It is just as flawed as uncritically accepting the production of dozens of different documents in the name of some Ruminated Ultimate Process. Documentation, like any other activity, needs to be created on a prioritized, return-on-investment basis. We create documents only if those documents are needed, and will more than pay back the effort required to produce them.
Agile Methods require two kinds of documentation: Requirements and Design Documents. All other kinds of documents are optional within Agile Methods; but optional does not mean absent.
- Requirements. In Agile Methods, the requirements are documented one iteration at a time. Requirements are often identified long in advance of their development, but they are not fleshed out until the iteration in which they are developed begins. Moreover, they are written as automated acceptance tests. Other kinds of requirements documentation, such a narratives, workflows, and storyboards may also optionally be created.
- Design Documents. In Agile Methods the design is documented by creating unit tests using Test Driven Development. These unit tests are working examples of how to use each part of the code. Other kinds of design documents, such as class diagrams, interaction diagrams, state charts, ER diagrams, etc. may optionally be created too.
Documents that the development team decides they need, are simply created as and when they are needed. Documents that the business decides they need, and that the development team does not need for their own purposes, are written as story cards, and estimated, planned and scheduled as all story cards are. If they never get selected for an iteration, then they must not have been all that valuable to the business. If, however, they get scheduled for an iteration, the business must have considered them important enough to schedule.
A friend of mine drew up some requirements documents and referred to them as "agile pornography". I was amused, and had used the term as well. It's not dead on, but it's a good spoof on how some people perceive Agile.
I think that one of the things I miss without a project metaphor is a sense of how the system ought to work, how it ought to feel. That's probably worth a very short document. And maybe some design patterns or choices could be listed too. I guess that's a good use of a wiki, since you want the documentation to be added, changed, or dropped at any time by the team.
I'd also like to hear more opinions about how long documents should live once created. :-)
(btw: comment written via 'links2' browser)
I think that one of the things I miss without a project metaphor is a sense of how the system ought to work, how it ought to feel. That's probably worth a very short document. And maybe some design patterns or choices could be listed too. I guess that's a good use of a wiki, since you want the documentation to be added, changed, or dropped at any time by the team.
I'd also like to hear more opinions about how long documents should live once created. :-)
(btw: comment written via 'links2' browser)
Documenting design patterns and choices is fine, but the questions are "why?" and "who is it for?". If you answer those questions, you'll probably do it at the right time and let them live for the right amount of time.
In my experience with up-front-document-heavy projects, a lot of investment was made in the documents - they were discussed, modified, signed off, and put in a drawer.
In my experience with up-front-document-heavy projects, a lot of investment was made in the documents - they were discussed, modified, signed off, and put in a drawer.
I'll never forget the first time I wrote up a design document that started to explain the "why." During the review, one of the attendees said "Why are you saying all of this? You should just describe the system." I replied, "Aren't these thing things you'd want to know?" After a moment of silence, the answer was "yes."
Documents? Some time ago I wrote an article where I stated that code comments will help with the design. Welcome to
http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html
Denis Krukovsky
http://write-software.blogspot.com/
http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html
Denis Krukovsky
http://write-software.blogspot.com/
Certain key documents can serve as the foundation of every decision made regarding a software project. They are the papers everyone recognizes and carries to every meeting. They're the shared understanding of the software subject. Sometimes it's a structure diagram, an activity diagram, a flowchart. These are, in my opinion, the documentation that must live on. If any decision about the software is contrary to the understanding of the key documents, something is up that needs serious consideration.
Beyond those key documents, the only reason to have more is in the case that those documents don't provide the detail to support a given decision. In such a case, dive deeper into that topic, starting from one or more of the key documents. Do enough to support your decision making, going only as broadly and deeply as necessary to properly validate your next move. Keep them around long enough to get the software through the release, and then toss whatever isn't necessary for the next move. It's likely that it'll be outdated when you next need to look at it. Better to spend time recreating documents than to work with inaccuracy.
Beyond those key documents, the only reason to have more is in the case that those documents don't provide the detail to support a given decision. In such a case, dive deeper into that topic, starting from one or more of the key documents. Do enough to support your decision making, going only as broadly and deeply as necessary to properly validate your next move. Keep them around long enough to get the software through the release, and then toss whatever isn't necessary for the next move. It's likely that it'll be outdated when you next need to look at it. Better to spend time recreating documents than to work with inaccuracy.
What about documenting the overall methodology, i.e. the particular SDLC in use within our particular environment? In the ongoing transition to Agile at our corporation, the notion of a methodology and associated 'process' documentation (not necessarily process manual, could be WIKI), flows, phases, team roles, etc...has all been thrown out as 'not Agile'...
Comments?
Comments?
John,
Documentation is not anti-agile. If it were, then there would not be any agile books, articles, or blogs. I strongly the folks at your company to document the process you have determined to follow. As you say, this could be in wiki form, or in any other convenient form. This does not need to be a twelve-ton document signed in blood by every developer and stakeholder. Indeed, it should not be a static document at all. It should be something living and changing. It should be a core of ideas that set the tone and spirit of the software development teams, and it should be supported by articles, notes, blogs, and discussions accessible to all.
Documentation is not anti-agile. If it were, then there would not be any agile books, articles, or blogs. I strongly the folks at your company to document the process you have determined to follow. As you say, this could be in wiki form, or in any other convenient form. This does not need to be a twelve-ton document signed in blood by every developer and stakeholder. Indeed, it should not be a static document at all. It should be something living and changing. It should be a core of ideas that set the tone and spirit of the software development teams, and it should be supported by articles, notes, blogs, and discussions accessible to all.
Your response validates my thinking. I believe it's important to lay out an overall methodology reference, yes indeed in a 'living, breathing' manner, preferably on the WIKI. I feel this stimulates the growth of a strong community - everyone gets involved and is able to 'see' what the methodology is. The mistaken belief in our corporation is that Agile IS a methodology, where the fact is that it's merely an umbrella term for a collection of practices. It's important to have an Agile 'methodology' (XP, Scrum, whatever) that you can then adapt to the specific needs of your corporation, i.e. establish an end-to-end view on the WIKI. Would such 'documentation' be perceived as 'no value' or 'low value'? From your comments I'm guessing absolutely not. Thanks for your response.
Add Child Page to OnDocumentation