Functional Spec & Agile Processes

Question

In traditional Waterfall, requirements were gathered - typically in a MS-Word document - following an esoteric template. In a "strict" waterfall model, this document is frozen after the requirement phase and a Change Control / Change Management process is responsible for introducing controlled changes. (**) [Typically, the document is turned into a "living document" and eventually a "living nightmare"]

Currently, I've to lead a project that is a rewrite of an existing desktop application to web (from VB 6.0 to ASP.Net). The client has a baselined version of the application that he wants rewritten. [So requirments are frozen... No scope creep]. The data model to be reused as is. Only the front end/Business rules to be migrated. Looking at the application, I feel it's a at most 3/4 major screens and that's it.

Some of the team members want to document (old school of thought, in my opinion) the entire thing before they start on the new development. I & and some others feel, it shoud be relatively easy translate the UI to Web, to look up old code, write the business logic, do automated unit tests, proceed to integration tests and deliver screen by screen (or business function by function)

My question is: In an Agile development how I do I remain "agile" if I were not to optimize this. My opinion is writing detailed documentation is anti-agile. What do you think? How would an agile guru approach the above problem (of rewriting an existing VB 6.0 app to ASP.Net)?

---

Disclaimer: Creation of a 1000 page Functional Spec could possibly be to meet contractual obligations, a political necessity, the system could be genuinely complex (now, definition of "complexity" is a journey unto murky-land).

Answer 1

Agile does not mean "no specs." It mean test and release early and often (but not necessarily to production).

The backlog in Scrum is the "spec." If you don't actually write down and manage the list of features, you WILL lose features, and you will NEVER be able to figure out when the product will be released (won't be able to estimate amount of work left because you have no idea where you are or how much there is left to do). The list of features MUST be managed by someone. The easiest way to do that is to write down everything the product should do (you can get as intricate in the wording and definition as you want) and keep track of what has been completed and what is left to do. How else will you assign work to developers and report status to "management?

Answer 2

Since you have a document describing what the product should do, I would use it as the initial backlog and start splitting the work in bite size pieces ordered from highest to lowest priority. Each set of pieces would then be handled during an iteration. In brief, use Scrum with your initial document as the backlog.

I would not go straight to the implementation without doing this prioritization work. It does not require a lot of writing but more referencing the pieces you want to tackle.

I would not document the whole thing upfront.

In addition, you will have some tasks directly related to the platform your tackling and those tasks need to be captured and added to the sprint backlog.

Also, you may realize that you don't want to implement all the requirements after a few iterations.

Answer 3

If creating a Function Spec is a contractual necessity you should think really carefully what goes in it. You could be refused payment if you fail to deliver what you promise in your functional spec.

Unfortunately you're not going to remain very agile if you adopt this process. Does the client really want the same functions for the re-written application? If yes, then why is it being re-written? I'm sure that there a features that are never used.

I would not bother to document the old version. You have a reference already, the application itself. There is no ambiguity in the software.

Document writing is not anti-agile. Designing something without prioritising and getting feedback from your customer is. An important aspect of agile is getting buy in from the customer. If they don't believe it, then the project will have a harder time than it should.

Answer 4

I've put a lot of thought on the subject - we work in a Scrum environment, and we've ended up having difficulties to organize the documentation.

What I'm heading to at the moment, though it's quite early so I don't know if it'll pass the long term test, is to use a wiki for the documentation.

Basically, the workflow is the following :

1. Stories come up in the backlog
2. Story gets picked up by a programmer
3. Programmer does the code, and in the DoD (Definition of Done), also has to write some tests against the new functionnality, and has to edit the wiki to add a page for the new functionnality.

The wiki is organized with mediawiki templates, pretty much inspired from mediawiki extensions doc pages, with the name of the functionnality, the version it has been introduced into, anything that can be usefull. The template adds pictos to distinguish between different kinds of features (and of their status).

At the end of the day, the wiki has the great advantage of letting you add the documentation page without being bothered about where or how to put it, but obviously regularly you need someone to come behind and organize the mess.

The important thing to keep in mind, whatever tool you use, is that the developper should write some doc just after the development has taken place (including technical aspects) - and not before, and not months after...

Answer 5

First, you can produce documentation and remain agile, if the customer or the Product Owner requests (read is ready to pay for) to have documentation.

Grow your documentation incrementally and iteratively, as you'll do with code. Test a little , code a little and ... document a little.

I see three ways of doing this : either include the time to write the documentation in the tasks estimation, create documentation specific tasks, or have documentation backlog items/stories.

The risk with the documentation stories is that they may be planned very late, a long time after that have been implemented, so I won't recommend this.

Documentation tasks have the advantage of being visible in the iteration planning, so they should not been forgotten over overlooked.