Extreme Programming Challenge Twenty One

Scenario:

Developing a commercial application and attempting to apply XP practices. How does one keep on-line and/or printed user documentation in sync as the application develops?

Option 1: Wait until release code is "locked" and write the docs.

This is not desirable because we "lose time" waiting for the docs for an otherwise deliverable application.

Option 2: Let the developers refactor the docs as they complete the features.

Developers effectively communicating to non-technical users? Please.

Option 3: Convert PairProgramming to TriadProgramming? by adding a tech writer to each pair.

Expensive!

Option 4: Compromise. Have the tech writers document each feature (UserStory) when it is completed and require the developers to communicate any later changes to the tech writers.

Complicated and error prone but otherwise cost effective.

Option 5: Meta Programming (Documentation as source code). Develop the documentation in a markup language (e.g. XML) and then generate code from it. Works best for reference documents. I have used this successfully for low level hardware interfaces, using FrameMaker->HTML->C+VHDL, instead of XML.

Shouldn't we think of the option where a developer has tech writing abilities? After all, aren't most of us educated at a liberal arts college? Don't we know how to write? Many TWers have nothing more than a certificate. As a consultant / developer, I have to "iron man" and do it all. - LlewelynThomas

Where do you live/work? Most of the software people I know have degrees from non-liberal arts institutions - not all are CS grads, but most are from technical colleges. A small exception is made for the Web professionals, who do tend to arts degrees, but that's more due to the visual arts nature of web work, rightly or wrongly. -- PeteHardie

In San Jose, with clients all over the Bay Area. Perhaps I've only met other programmers with BAs/BSes? I've never met a DeVry or CLC graduate working in either consulting or at technically-oriented client companies. - LlewelynThomas

I'm not just talking about DeVry grads, but also MIT, CalTech, and the horde of Engineering Colleges, where it is possible to take only 3 semesters of English, including a semester of Tech Writing, which is a drop in the bucket to the volume of technical courses. -- PeteHardie

Taking *only* 3 semesters of critical thinking and writing is obviously not a 'good idea'- your example engineers would be ill equipped to proceed to higher degrees or any occupation that required clear communication. -- LlewelynThomas

There's also the case of developers who are intelligent and well-educated, but are not competent at writing in whatever language(s) the customers need for documentation. This case requires technical writers. And a degenerate case would be where the technical writers and the developers don't speak a common language, requiring translators as intermediaries. -- KrisJohnson

What have I missed? How could this problem be avoided altogether? Anyone have any successful experiences here?

A previous employer distinguished between two forms of documentation. One is project docs, which are generated using a combination of access databases, HTML summary-generators that process our headers, and our in-house WikiWeb based on CvWiki. This stuff is way too higgledy piggledy right now, but it's slowly integrating into something that looks like a developers' intranet.

The other form is user documentation. We have a tech writing team who track our UserStories and CRC meetings, so far with mixed success. It might be possible to involve the tech writers directly in our StandupMeeting(s), but things don't change from day to day enough to justify that right now. -- PeterMerel

I have also worked with HTML summary generators for project docs. One of my co-workers was fascinated with the concept and even talked me into working all kinds of odd tags into my method comments in order to improve the results of the "harvest" process he was developing. It was really cool. It was also a major pain. Debatable whether the cool was worth the pain.

However, right now I am really most concerned about user documentation. Sounds like you are following a variant of Option 4. It also sounds like you have run into some of the same difficulties I have. I have found that the communication between development and tech writing breaks down when change is too fast or too slow. Even if the tech writers don't join your StandupMeeting(s), I have found that it helps if they are in the same BullPen? with the rest of the development team. "Helps" is a key word though. Still seems like a lot of stuff slips through the cracks and we end up trying to TestInQuality at the end of the project. -- JeffShelby

Question: In my experience, I've noticed that some tasks get implemented faster than they can be added to the user documentation and some tasks take a long time to implement but can easily be added to the documentation. Also, user documentation should only (and always) be updated after the task is merged into the main stream because you don't want to document a feature that gets rolled back (and you don't want undocumented features). So, how do you effectively deal with the two project schedules being out of phase? Perhaps run the project in parallel between the two camps, synchronizing at the story card/task level. This may be similar to QA scheduling requirements if you have a separate QA department. -- SunirShah

how do you effectively deal with the two project schedules being out of phase?

Right now, I am thinking that the solution might be to convince the tech writers to adopt more of a multi-pass authoring strategy where they add detail on each pass rather than write the "complete" documentation in a single pass. It might work like this:

Use the StoryCards to generate an outline Use knowledge gained from sitting in on design sessions to describe the purpose and general strategy for using each feature. When a System Test passes, fill in detailed operational procedures, examples, etc.

In this way, the tech writers are trailing the developers at the shortest possible distance while minimizing rework. This would seem to get us to a good baseline document but it doesn't really help keep it synched when changes are made to an existing function. -- JeffShelby

When working alone, I have found it very useful to do the user documentation first (it helps the design) and then code from the documentation. I can't claim to have tried it in a team approach, but it might be worth a try. JimRussell

Hmmm... Writing unit tests first had replaced this technique in my mind but now that you mention it the two practices might work together. Have to think about this more. -- JeffShelby

Shouldn't writing documentation (which is a kind of code for human beings) be able to use the same methods as writing code for the computer.

Its called for on a feature card
Its split down into tasks
A pair writes a test for their task (which would be a usability test in this case)
Then pair writes the documentation, tests it, if it passes integrates it into the release. The question then becomes, can you test the documentation effectively without having the code it documents running? -- Kenneth Tyler

In my opinion, testing documentation is a _very_ different thing from testing code, and it will only lead to confusion if we pretend that we can use the same methods for it. There is no such thing as an "automated user" to whom we can hand the latest release of our user documentation, see if he succeeds or fails at doing the documented tasks and make sure that his success score stays at 100%. :-) -- DmitryJemerov

Does any of this discussion mesh or refute the ideas in WriteTheUserManualFirst? -- SkipSailors

See ExtremeProgrammingChallenge