Manifesto Musings #3

Working software over comprehensive documentation

This line seems to me to be the least useful of the bunch, if only because it is so obvious as to seem unnecessary. Software without documentation may or may not be useful; documentation without software is always useless.

This line causes technical writers a lot of angst, though, so maybe I will approach it from that perspective as a straddle the career boundary.

Part of the angst seems to be rooted in a tendency for people to approach Agile stuff in a restrictive, black and white fashion. Most tech writers being in the business of providing customer-centric documentation of some kind, there's a tendency to think that Agile means getting rid of that wholesale, and I don't think that's what is actually meant. It is fairly common, though, to see "X has more value than y," morph into, "So you don't do y at all then. Good luck with that." Cue rolled eyes. This is of course a straw man; I've yet to encounter any Agile proponents or texts that make that kind of prescription. The whole point of Agile is to recognize that all knowledge, all practices, are contextual and contingent. It's the assumptions and absolutes that gets projects into trouble.

Regarding tech writers, there are a lot of conversations to be had around the question of how to fit end-user documentation into a Scrum team, and I haven't found any perfect solutions myself. I'm biased toward making the tech writer just another member of a cross-functional team. That's one team, not the three or four that writers are (in my experience) expected to cover, ensuring that they will spend half their time context switching and never reap the benefits of the team structure. They will doubtless pick up some additional useful skills while doing so, and some other members of the team might learn to write. I should note that I have a strong bias in favor of generalism vs specialism, and I've never gotten a chance to see how well it would work in practice.

Back to the Manifesto. I think that the signatories were thinking of "documentation" in the broad sense of the reams of planning documents produced in a typical waterfall project, and for which there is no good collective noun. This documentation is neatly stored in three-ring binders at the end of a project and never looked at again, and of course all of it is useless if the product is never finished.

I've been in a fair number of the meetings where these documents are produced, debated, and refined, and those are hours of my life that I won't be getting back. I did write a lot of product documentation using those plans as an outline, but it's certain that none of them were truly reflective of reality as it eventually appeared in the product. I've written a lot of product documentation without any of that stuff, too.

Whatever kind of documentation you're thinking of, it may or may not have value depending on the context (even planning documents have their place!). But if you don't actually produce any software at the end of the day, the value of the documentation is zero.