For example take the following story:
As a developer implementing an algorithmic trading application, I need to put price constraints in place to ensure that the algorithm operates within safe boundaries.The acceptence criteria is pretty clear "it is done when the developer can add price contraints to his trading algorithm". The functional part of this is easy to measure and understanding what to build is also clear. But what about the documentation part of the story? What is the acceptence criteria? "A procedure that explains how to implement a price constraint." That is not easily verifyable. I could write a procedure that is simple and just walks the developer through the steps:1: add this line of code. 2: include these two parameters in the argument list. etc. Does that really satisfy the requirement such that the developer knows how to implement the price constraint? It is ultimately going to involve some subjectivity.
The second question is wheter the story, with the documentation included, could be fit into a single sprint. The documentation cannot really be written until after the implementation is underway and cannot be QAd until after the implementation is complete. The developer will also need to spend some time with the writer providing information. So, should any story with documentaiton impact be split into two stories: one for engineering and one for documentation (the documentation story is dependent on the engineering story)? IMHO splitting stories into a programming story and documentation story is the best way to do it, but it leaves open the possibility that the documentation story will get prioritized out of the release.
Another question that including documentation in agile frameworks that I've heard involves having skin in the game. The concern is that writers, because they cannot write code, may have sprints where they have no active tasks (no skin in the game). In traditional development models, the programmers get started building stuff right off the bat and the writers settle into what they call "disovery mode". The writers are researching what the programmers are building. At some later point in the release cycle, after the programmers have built a bunch of stuff, the writers start writing. So, it makes sense that there is a concern that in early sprints, writers will have no skin in the game. However, I think that this is not going to be a concern in actuality. The writers always have user requests that filter in from previous releases that can be completed in early sprints. They also have areas where they know the documentation can be improved. Given that functionality will start appearing after the first sprint, the writers should have something new to document by sprint number two.
One more question. This one combines concerns from both the previous questions: How do you create acceptence criteria for a story like "understanding the user roles for Apama" or "research the Sonic WS-Security implementation"? My opinion is that you don't because they are not stories they are tasks that need to be completed as part of resolving a story. The task may require an entire sprint, but that does not change the fact that it is just a task. I also don't think that the task will take an entire sprint because such tasks will be constrained tighter than "research WS-Security" to something more along the lines of "research how to secure a Web service using Kerberos tokens." It is possible that some reasearch tasks may take more than a sprint, but programmers may also need to spend a sprint doing research on ways to implement some functionality. The framework has space for it.