Software Documentation and Agile
Developing documentation (both end-user and internal) in an Agile software development environment can present a few challenges, but overall presents many opportunities for technical communicators.
Agile, by its nature, provides relatively short cycles for developing end-user documentation. However, Agile projects succeed or fail based on their internal documentation, so technical communicators are a required part of the process. In fact, we are involved from day one.
Overview of Agile
When I was first introduced to Agile over 10 years ago, the original "Agile Manifesto" for software development (http://agilemanifesto.org/) struck a bit of fear in my heart. The Manifesto values "Working software over comprehensive documentation." But the seventeen signatories were not referring to end-user documentation, but internal documentation. (After I started breathing again... I learned more. Our company's owner had purchased each team member one of the few books on Agile available at the time and made it required reading. There has been quite a bit written since.)
Key principles of Agile include:
- Small, self-organizing teams
- "Just enough" internal documentation
- Willingness (and the ability) to change direction quickly
(A list of all the principles can be found here: http://agilemanifesto.org/principles.html
Among the methodologies used are:
- Scrums (short, daily meetings)
- Kanban planning (a visual, flexible task management system)
- Sprints (very short - usually 2 week - cycles for software deliverables)
Bottom line, the Agile method attempts to keep everything lightweight and flexible. This requires that team members work closely together plus - and this is key - are dedicated participants in the process.
How Technical Communicators (TCs) Fit in the Process
TCs get involved in the development process from day one, because each Agile team includes a technical communicator. This is partly because Agile teams are cross-functional; but also because the internal doc for the project must be captured. This doc is needed for the project stakeholders, the organizational memory, and for audit purposes (this is dependent upon the industry you are working in).
Documenting for the organization memory is important to the process, because Agile strives for continuous improvement that will increase both the speed of development, and the quality of the software. Project artifacts are needed to achieve that goal.
End-user documentation for the project is a given, but its development must be adjusted to the Agile process. The biggest process change for TCs is that user documentation must be written in small pieces - before the entire project is scoped. Also, detailed requirements documents are replaced with user stories.
One thing that should feel familiar: user documentation will always be one Sprint (iteration) behind.
In an Agile process, end-user documentation should be ready for and included in the usability and quality assurance reviews. This feedback can be used to improve the documentation, plus it raises its visibility to the entire team.
As for internal documentation needed, the list includes:
- User Stories (requirement docs)
Acceptance tests (testing docs)
Project planning information (stored initially on white boards, post-its, index cards, etc.)
Reference documentation/code comments
Some of these are very simple to take on, but some will take a little creativity. For example, if your team is keeping planning information on a whiteboard, you may need to take photos of the board every day or week, and store that information for future reference. Creating reference documentation and capturing code comments can be handled automatically, depending upon your help authoring tool.
How Doc-To-Help Fits Agile
You can capture software reference documentation (namespaces, classes, methods, properties, etc.) and code comments automatically, with the right help authoring tool. Doc-To-Help can handle this, plus there are other ways it meshes well with the Agile process.
#1 - You can store all of your project docs (internal and external) in the same Doc-To-Help project. Docs can be Word, HTML, or XHTML (XHTML docs are edited in Doc-To-Help's built-in editor). You can mix doc types in the same project. Bottom line, everyone on the project can write in the format they are most comfortable with.
#2 - Using conditions, you can mark entire documents for either internal or external use. Then you can build the output you need for either purpose based on those conditions. You can even create conditions for "testing," "requirements," "planning" - whatever you wish (and that includes the end user docs). Outputs include HTML Help, browser-based Help, pdf manual, Word manual, and more.
#3 - Doc-To-Help has source control. If you need document check-in/check-out to avoid editing conflicts, you can use Doc-To-Help's built-in source control, or take advantage of its interface to Microsoft Team Foundation Server.
#4 - Creating reference documentation and capturing code comments is easy, because Doc-To-Help includes a Microsoft Sandcastle plug-in. This puts a Wizard-like interface on creating reference documentation. All that is needed from software development is the .NET assembly file and the XML comment file. (By the way, software development can use ComponentOne IntelliSpell to check their code comments in advance.)
#5 - If you need automated builds, Doc-To-Help includes a utility that you can use to build outputs in batches.
#6 - As the project hits specified milestones, you can use Doc-To-Help's "Save Project" feature to save the internal and external documentation for that cycle, and then you can continue on with the next. This will preserve the project documentation for later reflection (see the Agile Principles) plus you will have a record for both organization memory, and perhaps the auditors.
Wrapping up
Within an Agile environment, our TC challenge is to provide end-user documentation, while learning about and taking on new responsibilities. In the end, project knowledge must be documented for Agile to work. Although Agile emphasizes keeping documentation "light," internal doc is a must for stakeholders, and the organizational memory.
Remember, as in any process, Agile has specified guidelines and methodologies - but you need to tailor it for your situation. Be flexible and make it work for your project.
This post touches on a very small portion of Agile and its theories. The websites below are a great starting point for learning more.
Further Reading
http://www.agilemanifesto.org/
MESCIUS inc.