So recently, we've just finished the first phase of our project.
We used agile with fortnightly sprints. And whilst the application turned out well, we're now turning our eyes on some of the maintenance tasks.
One maintenance task is that all of our documentation appears in the form of specs. These specs describe 1 or more stories and generally are a body of work which a few devs could knock over in a week.
For development, that works really well – every two weeks, the devs get handed a spec and it's a nice discrete chunk of work that they can just do.
From a documentation point of view, this has become a mess. The problem with writing specs that are focused on delivering just-in-time requirements to developers is we haven't placed much emphasis on the big picture.
Specs come from all different angles – it could be describing a standard function, it could describing parts of a workflow, it could be describing a particular screen…
And now, we have business rules about our application scattered across 120 documents. Looking for any document for a particular business rule or function in particular is quite hard because you don't know which document has this information, and making a change request is equally hard because once again, we are unsure about which spec to make the change.
So we have maybe a couple of weeks of lull before it's back to specing out functionality for the next phase but in this time, I'd like to re-visit our processes. I think the way we have worked so far in terms of delivering fortnightly specs works well.
But we also need a way to manage our documentation so that our business rules for a given function / workflow are easy to locate / change.
I have two ideas.
One is we compile all of our specs into a series of master specs broken by a few broad functional areas. The specs describe the sprint, the master spec describe the system. The only problem I can see is
1) Our existing 120 specs are not all neatly defined into broad functional areas. Some will require breaking up, merging etc. which will take a lot of time.
2) We'll be writing specs and updating master specs in each new sprint. Seems like double the work, and then do the devs look at the spec or the master spec?
My other suggestion is to concede that our documentation is too big of a mess, and manage that mess going forward. So we go through each spec, assign like keywords to it, and then when we want to search for a function, we search for that keyword. Problems I can see
1) Still the problem of business rules scattered everywhere, keywords just make it easier to find it.
anyway, if anyone has any decent ideas or any experience to share about how best to manage documentation, would really appreciate it.
Best Answer
This is one of the major problems with "big-A-Agile" development: it's primarily focused on development. If system documentation matters to your users (and it usually does), your technical writers and their work-product need to be part of the sprint. In the "small-a-agile" community, we've come to understand that there is more to product than just code. We've integrate testers and testing into sprints, including making sure the testers know enough about what is being coded that they can test inside the sprint. We need to do the same with the technical writers, although I don't know anyone who's doing it yet.