Functional Spec & Agile Processes [closed]
Asked Answered
D

8

12

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).

Dabchick answered 24/10, 2008 at 21:55 Comment(2)
What is meant by "document" - and why do you feel agile is the appropriate development methodology? You're already at the bottom of the traditional "V" process. What value would agile add? Contrary to popular opinion, agile is not always the best way to run a development program...Saving
I'm voting to close this question as off-topic because this is not a programming question as defined in the Help Center.Auramine
A
12

First, you can produce documentation and remain agile, if the customer or the Product Owner requests to have (read is ready to pay for) 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 or overlooked.

Angst answered 26/12, 2008 at 14:24 Comment(0)
U
3

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?

Upsydaisy answered 24/10, 2008 at 22:17 Comment(1)
I didn't mean "No specs"... but how detailed should it be?... And in context with the current problem I am facing...Dabchick
L
3

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...

Legerdemain answered 25/10, 2008 at 8:40 Comment(2)
I do have a Team Wiki [ScrewTurn Wiki]... The idea of Func Spec as a wiki... Hey, I like it (of course, I'm hoping conversion of the wiki page into PDFs should suffice if client were to demand a copy)Dabchick
I love the suggestion that you document immediately after you develop. Bloated specs best serve lawyers.Mohler
I
3

In my view the functional specification is necessary depending on how involved is the tech team with the product and how senior is the team. If the tech team is involved in the product definition you'll definitely need less documentation because there will be less room for assumptions. If you have a team of engineers that are juniors you need a stronger documentation or else things will not be done the way they were defined in the end of the sprints.
Also be aware that remote teams need more documentation in the form of functional specs due to the natural barrier of not being close to the stakeholders and product visionaries. Having upfront functional specs is a feature of agile. I saw a lot of tech teams where the tasks where solely described by a user story and quite often I saw those teams failing to achieve the releases and meeting the stakeholder's expectations.

This subject is very broad and there are a lot of opinions but in my view this can be reduced to the fact that the developers should not have to guess the requirements.

In fact I believe that the success and quality of the deliverables is inversely proportional to the number of guesses/assumptions that the developers need to make. I think agility increases with how well specified is something because you will have less mistakes and will spend less time correcting those mistakes.

Immortal answered 11/4, 2016 at 8:58 Comment(0)
C
2

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.

Cobbler answered 25/10, 2008 at 8:31 Comment(1)
Dave, on the one hand you say if I were to write a detailed functional spec, I'm not going to reamin very agile. And you're saying [detailed?] document writing is not anti-agile (I was actually talking about exhaustive, long winded document)... Aren't the two contradictory?Dabchick
I
2

As already pointed out, Agile does not mean little to no documentation - "working software over comprehensive documentation".

The way I approach documentation is almost to flip things on its head and to consider just about everything part of documentation (including code and unit tests as technical specs). So, a story (or whatever other mechanism you use to divvy up work) describing a business/user requirement should be detailed enough to be estimated by the team doing the work; otherwise, it is incomplete and vague. Further, something I do in my own practice, if the story (or whatever) is estimated to take longer than one working day to fit the team's definition of "done" it should most likely be broken down (this atomizing then compiling eventually leads to pretty extensive documentation, but does not assume as many unknowns as not doing it will - and can lead pretty interesting reuse and pattern revelations).

Example using BDD style requirements:

Given I am working on a document
When I select "Save As..."
Then a menu should appear allowing me to choose a name, 
and a file type, 
and a location in the file system,
and a file should be created in the file system

We may need/want to add UI elements to accomplish this, menu items, storyboards, keyboard shortcuts, etc. to this description (we may have multiple variations on the same theme of "saving a file"). And so on.

All of these related artifacts can be attached onto the base story/requirement; resulting in more complete documentation. But, only add those stories you actually implement to your documentation of the web version of the software.

Here's where things get kind of flipped on their head and become more "Agile". During development, and after development, revisiting the documented requirement and adding changes/modifications/improvements made by the team edits are made (without having to go through a documentation-only CCB). The ability to edit/update the documentation and related assets without going through all the review boards and whatnot - or throwing the document "back over the wall" when we find out during development that the document is incomplete in some way makes us able to adapt to the unknowns - therefore, Agile.

This documentation should have some form of version control or history, which allows us to describe the system we desired, but also describe the system that was actually implemented - noting another answer/suggestions regarding documentation being part of the Definition of Done (something I also do). (Wikis are good for this; however, a fully integrated concept is a little more desirable - e.g., being able to relate a ticket to a file in trunk in the version control system would be nice.)

To kind of conclude. Creating exhaustive documentation up front, which cannot be altered during and/or shortly after the development effort, will keep you from being agile - able to quickly adapt to unknowns. However, to reference Leading Lean Software Development, wherein they mention that if policies do not allow for certain practices/processes to be used properly, then it doesn't matter if you say you are lean (or scrum, or agile).

One way to make sure you are not being overly exhaustive - probably could've used this mindset on this answer - is to only write what you need to when you need to (similar concepts exist in development in general). Another would be to get everyone to understand that you don't need to try and figure everything out up front (the biggest transition from Waterfall to Agile) - we will document every idea and it may or may not end up in a release. And, finally, deprecate (and remove) anything that no longer applies...I remember seeing documentation for a system once and, when I reviewed the system, half the document didn't actually apply to the system anymore.

Iiette answered 17/3, 2013 at 16:32 Comment(0)
T
1

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.

Trapeziform answered 24/10, 2008 at 22:30 Comment(0)
O
1

Agile has a Functional Specification document in the form of the agile Features list, Product Backlog and even as far into the sprint as tasks in the sprint Backlogs too. The fact they are not called documents doesn't make them any less. And the difference from the Functional Spec in waterfall?...Agile Functional Spec only contains what is required (lol) therefore is less voluminous, remember your "Working software over comprehensive documentation"?

Ovida answered 3/7, 2014 at 13:29 Comment(0)

© 2022 - 2024 — McMap. All rights reserved.