It is true that you can make most of your code simple enough to be readable by developers. They will have to follow a uniform coding standard, which is anyway good for code maintainability.

However even the best written code doesn't always translate to "code is documentation". Let's look at the reasons.

Any moderately complex software contains tons of code anywhere from 50, 000 to few million lines of code.

It becomes impossible for any developer to gain an understanding of the system with its full complexity just by looking at the code in a reasonable amount of time.

He definitely needs an architecture and design document to provide him an overall perspective and design goals of the document.

He needs a functional documentation to understand what the application is supposed to do.
This is actually much more important than it appears at first glance. Code represents the ground reality, what the application does at this moment, with its defects and all.
What it doesn't tell you is what the application ideally is supposed to do, how it is supposed to respond to a particular situation.

A well written project is backed by lots of test cases. If it is developed by a XP team rigorously following TDD (Test Driven Development) there should be much better coverage. However again in real life coverage in most cases is much below 100%. However even 100% coverage doesn't guarantee safety. The unit tests are developed by developers and are limited by the understanding and knowledge of the developer. In real life that translates to the fact that even the test cases do not provide adequate documentation of the functionality of the product, even for developers.

So in short test-cases-are-documentation doesn't cover all the bases even for developers.

Additional value of Good Documentation
Documentation can be easily validated by customers/marketing. They provide the means of independent testing of the application by third party of quality assurance team. Thus they provide additional checks and balances in ensuring the final quality of the product.

In my experience I have often seen developers realize some obvious mistakes they were making after apparently innocuous questions by the documentation team.

Good Documentation doesn't translate to verbose documentation. Documentation need not be lengthy and unnecessarily verbose. It takes a good technical writer to provide concise documentation with full coverage of functionality.

Producing high quality documentation should be high priority for the team management. I have seen lots of really good products fail in the market due to lack of clear documentation.
Unfortunately most casual reviews of a product are based on the available documentation.

Role of Technical Writers in XP project

In an XP project, documentation team can be part of the XP team. However as others have noted that it breaks the interchangeable paradigm of XP. That is not an issue as interchangeable paradigm adds maximum value within a particular group only. We don't expect developers to replace technical writers and vice versa.

However there are few practical issues. Technical writers often cater to multiple projects. If they are part of multiple XP teams that is bound to cosume much of their time. Also documentation written in the earlier part of a project are likely to change heavily over time questioning their value in being active members of the team from the start. They should realistically join a XP team in later stages of the project. However they should be passive observers to planning meetings to keep up with the happening in the project and understanding the resources required from them. They also act as customers of the project with their own user stories, which ensures they get bandwidth from developers to discuss/review their documentation. I have seen technical writers with proactive approach generally adds lots of value to an XP project.

Summary

  • Good documentation is still a strong requirement for any decent product or service and should be a high priority activity.
  • Software code and test cases, though immensely useful in understanding the funtionality of an application for developers, is not a substitute for documentation.
  • Good documentation doesn't mean unnecessarily verbose documentation.
  • Technical Writers should be part of an XP team, albeit with few adjustments to suit their unique role

Pages: 1 2