XProgramming
>
XP Magazine
>
Manuals in Extreme Programming
COLLECTED TOPICS: Adventures in C# |
Documentation in XP | Book Reviews
Manuals in Extreme Programming
11/21/2001
Let's think about Extreme Programming, software products, and their manuals. Some starting points:
- Everyone who has done software products knows that almost no one reads the manual. We know this from the technical support queries we get. We know it because most of us don't read the manuals either.
- Web apps don't come with manuals, and they're kicking butt. Some of them have a couple of help pages. Many have nothing but the instructions on the page and the flow of the buttons.
- More and more software today is delivered on a CD, and the only manual you get is the size of the CD box. Seems to work fine - science has found that more people read those little books - it's thought that they're looking for the lyrics.
- And hey: XP projects build the software with the highest business value first. The stuff at the end doesn't matter as much as the stuff at the beginning!
Put this all together:
- Write an easy to use product that doesn't require a big manual. Then - duh - don't write a big manual. Don't listen to the pointy-haired guy saying "but our customers expect big manuals". Your customer hates big manuals. He has shelves and boxes full of them just like you do.
- Make the product as easy to use as a web site. This will please the majority of your customers who don't read the manual anyway, and will reduce the size of the manual for those who do. Back injuries go down, customer satisfaction goes up. Stock price through the roof. Porsches all around.
- Document as you go. Plan to have documentation one iteration behind development. If you (the customer) decide to change things in some iteration, just remember that you're also deciding to change the docs in the next.
- Documenting a feature shouldn't be any more difficult than implementing it. If your programmers can invent the bloody thing from scratch in one iteration, your writers ought to be able to write it up in the same time and stay only one iteration behind. It's just reporting, after all. If the writers can't keep up, hold THEIR feet to the fire - it's their turn. Let them write Extreme Writing - Embrace FrameMaker in a few years if they need to.
When the product is code complete, it will be documentation complete a couple of weeks later. Two more weeks should give you the hard copy, and you can beat that if you get creative. For example, print the document before the ship date, and do an 8.5x11 supplement for the last two iterations' stuff. Better yet, don't print it at all. Do the docs in HTML and ship it on the CD or put it on the web.
Do you still need hard copy? Well, drop ship it direct from your printer. Or save a tree: give people a coupon. Many of them won't use it, and the mail service gives you a few weeks to finalize and print the manuals. Charge extra for the manual. Increased revenue, stock price, more Porsches.
But wait! Don't answer yet: there's more!
XP programmers do Continuous Integration and release all the time. Small releases, remember? So have XP writers cut their documents every day, week, iteration, release. They'll get really good at it, just like the programmers.
In a software product shop, Extreme Programming will wind up implying Extreme Business. We all know that one of the reasons the software has to be done by [insert impossible date here] is because it takes X long to do the documents, Y long to do the packaging, Z long to do the shipping.
What made them think the software schedule was flexible, when none of the others were? Probably it's just that programmers are loyal enough to try harder, and dumb enough to think trying harder makes them go faster. The shipping department knows better, and the writers are more articulate.
Well, bite me. XP teams can deliver software by the clock, with very good control over what's on the disc and what's deferred. An XP team with associated writers can deliver a documented product at most one iteration after code complete. I'm willing to bet that if you let the writers be part of the team, they can do better than that. The rest of business can get on board or face the fact that they, not the programmers, are the cork in the orifice of progress.
Let the shipping department take the heat for a change. Put some good writers in the room with the programmers and let them figure it out. Don't set their goals or their process, just let them see what's up. Maybe all they'll do is work from the release at the end of the iteration. Maybe they'll find a way to start writing half-way through the iteration. Me, I bet they'll write the Extreme Writing book as a side effect.
Extreme Programming. Ship better software, on time, while killing fewer programmers and fewer trees. Humanistic, my tail. XP is GREEN! And remember - it's not easy being green!