Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
One of the Four Core Agile values says "Working Software over comprehensive documentation" and this is explained as a good thing. Furthermore it is explained that rather than written communication (e-mails included), face-to-face meetings are preferred and "more productive".
I would like for someone to explain to me why or how is this a good thing?
In a organization I used to work there were heaps of working software that I had to maintain. The documentation was minimal and it was a nightmare. It didn't help that the programs were not modularized and were very hard to understand and with the most esoteric twists and very disorganized. Comprehensive documentation as very important was one think I took from that experience. It doesn't matter if the software works now if it is not going to work in the near future right?
And on face-to-face meetings, I had the same doubt. I very much prefer e-mails (written) You can say the most outrageous of things when talking but when it is written then it is a deal. Plus if you are in a multinational organization with several languages, it helps a lot
I would like to hear the voice of people with Agile experience. How is the above a good thing? Thanks
Working software over comprehensive documentation
Comprehensive documentation is sometimes seen as a way to demonstrate progress. "If we have a detailed specification and a weighty design document then we are making good progress towards a product delivery"
What working software over comprehensive documentation means is that we view working software as a better demonstration of progress than documentation. This is because comprehensive documentation can give a false level of confidence.
So there is nothing that says avoid doing any documentation. It is just saying that we should only do the documentation that is needed and not just do documentation because it is part of a process.
In your example where there the software is difficult to work with then more documentation may well be needed. Just don't write documents that never get used and offer little value.
Individuals and interaction over process and tools
Face-to-face communication has many advantages over other forms of communication. For example:
People use body language to give context to conversations
People use audible and visual clues as to when to start and stop talking - this helps to make conversations flow
Regular face-to-face discussions often help teams to bond together
Notice though that the Agile manifesto does not mention face-to-face communication. All it says is individuals and interaction. If you and your team have ways of communicating that are as effective as face-to-face communication then that fits just as well within the Agile approach. The important part is that we value interaction and having members of the team work closely with each other.
When all agile recommendations are taken into account there are no issues you mentioned in your question. Working software should also has good code standards and design.
Regarding your particular issue with a lack of documentation unit tests (TDD/BDD) could be very useful. Good code coverage can explain how code should work even better than detailed documentation. Agile methodology also welcomes simplicity so your entire architecture might be over-complicated
Regarding face-to-face communication. Just imagine situation when you detected issue in your product (web-site markup). Instead of writing long email with steps to reproduce and attaching screenshots, you just go to front-end developer sitting in your room or make skype call and start explaining problem. Developer quickly realizes that he forgot to include some script. So your will get answer in minutes while your email can be answered next day.
I think it would be necessary to clarify your needs on using agile first before you want to apply agile.
Agile is the recommended working framework for a highly unpredictable domain(you may also check Cynefin model for identifying your working contexts). In this domain, you do require "working software" and "good communication" to review and revise your development in a short-term iterative process. As a result, you can change and improve your software based on the feedback from your software. This is proven to be the most effective and efficient way to build software in high competitive business world.
However, in your organization, you are maintaining legacy software with limited documentation. This context is totally different from what agile is designed for. You need optimization in your world, not testing or growth seeking. In short, process/tools and documentation are more important.
Regarding email communication, there is no doubt that email makes the deal, but you could never make a deal by just using email. It is the same as how you apply agile. You should apply both face-to-face and email based on different situation.
I would regard Agile as a framework more than a methodology. The concept there is to allow you build your own process based on your own working environment.
Documentation is an expression of a shared vocabulary, so it should be consistent from the epic all the way down to the comments in the code:
Documentation should be comprehensive and understandable. Using examples is recommended.
Language between feature stories, technical stories, pseudocode, and assertions should have naming conventions
A feature that people do not know about is a useless feature.
Lack of documentation can be a symptom of the lack of a marketing plan
A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation.
Lack of documentation can be a symptom of the lack of usability, accessibility, and information architecture
Adjust the documentation. Doing this first gives you an impression of how
your changes affect the user.
Lack of documentation can be a symptom of a lack of focus on the user and the maintainer:
Software is not useful by itself. The executable software is only part of the picture. It is of no use without user manuals, business processes, design documentation, well-commented source code, and test cases. These should be produced as an intrinsic part of the development, not added at the end. In particular, recognize that design documentation serves two distinct purposes:
To allow the developers to get from a set of requirements to an implementation. Much of this type of documentation outlives its usefulness after implementation.
To allow the maintainers to understand how the implementation satisfies the requirements. A document aimed at maintainers is much shorter, cheaper to produce and more useful than a traditional design document.
And understanding the purpose of any project requires building a relationship between the project timeline and the source code history:
Write the change log entries for your changes. This is both to save us the extra work of writing them, and to help explain your changes so we can understand them.
The purpose of the change log is to show people where to find what was changed. So you need to be specific about what functions you changed; in large functions, it’s often helpful to indicate where within the function the change was.
On the other hand, once you have shown people where to find the change, you need not explain its purpose in the change log. Thus, if you add a new function, all you need to say about it is that it is new. If you feel that the purpose needs explaining, it probably does — but put the explanation in comments in the code. It will be more useful there.
References
Vim documentation: develop
SCRUM-PSP: Embracing Process Agility and Discipline (pdf)
Secure Software Development Life Cycle Processes | US-CERT
An Uneasy Marriage? Merging Scrum and TSP (pdf)
TSP/PSP and Agile-SCRUM: Similarities & Differences
GNU Emacs Manual: Sending Patches
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I am a long time agile advocated but one of the things that bothers me about Agile is that a lot of agile practitioners, especially the younger ones, have thrown out or are missing a whole lot of good (non Scrum, non XP) practices. Alistair Cockburn's style of writing Use Cases springs to mind; orthogonal arrays (pairwise testing) is another.
I read mostly Agile related books and articles and work with mostly Agile folk ... is there anything I'm missing?
It might be interesting in 5-10 years time to see how maintainable these systems are when nobody wrote down why a particular decision was made and all the people involved have left.
is there anything I'm missing?
Yes, I think a lot, but only if you are interested in Softawre Development Processes.
I like this paraphrase:
Each project should be as agile as possible but not more agile.
Not every project can be agile... but I think 80%+ can.
I see Agile as "car of the year". It is very well suited for most of the people, but if you need/want something special, for example car able to speed 300KM/H or car able to carry 20 tons of goods you need something else.
There is also so many cases when one may want something else than "car of the year" that requires a book to write them down :-) I recommend you Agility and Discipline Made Easy: Practices from OpenUP and RUP. In this book you'll find many "missing parts" very well illustrated. The key to understanding is that Agility is only a (requested) property of software development process which sometimes cannot be achieved. The book describes several Key Development Principles (which are basis for RUP) and explains which level of "ceremony" and "iterativeness" follows from using them on different levels of adoption.
An example
Practice: Automate change management and change propagation
In your project you may require very advanced and strict change management and decide to "Automate change management and change propagation" by implementing custom or re-configuring existing tools and by using Change and Control Board.
Effect: This most probably increase level of "ceremony" in your project.
(...) have thrown out or are missing a whole lot of good (non Scrum, non XP) practices.
Scrum is not prescriptive, it's up to you to choose how to do things. In other words, nothing forces you to use User Stories for example (even if User Stories work for lots of teams, there is no consensus) so feel free to use (light) use-cases if you think they are more appropriate in your context. To illustrate this, Jeff Sutherland reported he would never use User Stories again for PDA device projects (they use some kind of "light specifications" in his current company). And the same applies for testing, use whatever works for you. To summarize, if you find XP not flexible enough, use something else... and inspect and adapt.
Iterative development.
In practice, agile teams may do iterations (or anything for that matter, agile is a kind of "true scotsman"), but agile processes don't require or define iterative development sufficiently.
Take RUP, for example - clumsy and bloated, it does compile a few good methods for long-term development that agile misses.
On a general note, agile is a way to steer clear of problems: how to avoid long term planning, how to keep teams small, tasks short, customers involved, etc. It works more often than not, but sometimes you have to face and solve problems: how to reach strict deadline, make big team work, achieve distant and complex goals, make customer refine requirements. That's when one needs to look beyond agile.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Looking for work at the moment, I'm seeing a lot of places asking for Agile experience, but until I get a job with a team that is using Agile, I suspect I'll never get the experience.
Is it possible to adopt Agile methodologies with just one person?
Sort of answering my own question, there's similar questions at :-
https://stackoverflow.com/questions/1407189/can-agile-scrum-be-used-by-1-or-2-developers
(I guess I should get better at searching.)
You seem to be coming at this from a work experience point of view; if you are looking to build relevant experience to get you a job on an agile project I would probably think a little more laterally.
Firstly could you work with others, maybe on an open source project? That would be a good opportunity to try out agile methods with others who may have more experience.
Secondly, you could look at using some of the common techniques or tools, even if it's just to learn how the tools work - e.g. you could set up a continues integration server to run builds and unit tests when you check in code. If you are working on your own you won't gain much in terms of productivity by doing this but you would gain some skills and have something relevant to say to future employers which would indicate you are committed to the agile style.
Yes
Check out PXP or Personal Extreme Programming.
http://portal.acm.org/citation.cfm?id=1593127
Summary from the paper:
Personal Extreme Programming (PXP) is
a software development process for a
single person team. It is based on the
values of Extreme Programming (XP)
i.e. simplicity, communication,
feedback, and courage. It works by
keeping the important aspects of XP
and refining the values so that they
can fit in a lone programmer
situation. PXP can still be refined
and improved. It is in the tradition
of XP practitioners to vary XP to
encompass whatever works. We hope
that PXP inherits these pragmatic
roots, as well. Giving up XP tenets
like pair programming is not
necessarily a tragedy. We still
believe that following XP strictly is
a more effective way to pursue
multi-person projects. But we are also
convinced that many of the XP
practices and methods can be applied
to individual work. The PXP
approach tries to balance between the
"too heavy" and the "too light"
methodologies. PXP will inject the
right amount of rigor for the
situation without overburdening the
team with unnecessary bureaucracy.
Yes - it is possible to do many agile practices as an individual.
If you already know how to do these, you can do them as a sole developer:
test-driven development - great place to start
refactoring
continuous integration
doing the simplest thing that could possibly work (and evolving it through refactoring)
automated deployment
planning meetings (a team of one plus customer)
Things you can't do on your own:
pair programming
CRC/RRC workshops (... you'd have to talk to yourself quite a lot)
Pair programming would be hard this way :)
Let's check Agile Principles:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
You can do all of those things even while working on some personal project alone. You can use also GTD while working alone, you can develop your product through iterations, you can adopt timeboxing, you can ask some family members or friends to do usability tests with you (and this works really well).
As a conclusion, you can really get tons of Agile experiences alone. I strongly recommend you to read some books first tho, as some of principles can be easily misinterpreted.
Some aspects can be done alone: running a product backlog and using a task board come to mind. See what the secretGeek is doing.
Of course some cannot: pair programming, scrums etc...
I recently interrupted a big project. It was a medical software project. While working on it, I realized some patterns about solo programming. I want to share my experiences here:
Your software's working logic must always reflect the real world. You catch fish with fishing rod, not baseball bat; so forget it.
Always start building from the project element to which all other elements refer. That makes sense if you think that like the function in a software project which is called at most. That might be database modeling. It would be useless if you model data access layer first, before modeling database.
Never mind changing variable names. That's the most written entry in a programmer's diary; so no need to be ashamed.
Methodology changes the world. Make worth of it. Make every single logical process with a function or procedure. When project gets huge you will understand thats the best way.
If you're not designing a language compiler in assembly do not hesitate using huge procedure call chains in which one calls another and that calls another and so on. Use methods everywhere, nearly resemble every single entity with classes and be modular.
Modularity is everything. Set modularity your primary goal. Have i said it is everything meanwhile?
Last word for beginning the project. If you're building an apartment you install main entrance at last. But when using, you enter the building from entrance. Be aware.
These are some of my design principles I learned and learning day by day. I hope having been useful. Do your best.
While some Agile practices are directly targeted at more than one person teams, they are just practices, they are just a mean, not an end. I mean, Agile is not about doing pair programming, stand up meetings, etc. Agile is about maximizing the customer value while minimizing waste to provide the most optimal ROI. Agile is business oriented, practices are just a way to achieve this goal in a given context. So, back to the initial question, it's definitely possible to adopt Agile practices (that make sense in your context) to maximize the delivered value: continuous planning, limiting Work In Progress, Stop-the-Line culture, time boxing, high quality, just enough specifications, just enough and just in time documentation, etc, etc.
Definately. Agile is very flexible in terms of how many people are involved. Some methodologies, like Scrum, focus mostly on doing as much as possible in a limited time, like two weeks (sprints). That includes whatever you want it to. If your team requires QA, then that is part of it. As a loner, you decide what you want to include.
After the scrum sprint, you look at what you could have done differently to get more done, and move to the next one.
Some other methodologies focus more on getting features done in each iteration, say three small features developed, tested and refactored.
As you can see, there are tons of ways to apply agile to any project. You decide which aspects you want. Though obviously one integral part is doing things in small increments.
Yes
XP/TDD scales from one to one thousand. Pair programming is optional.
YES.
Agile is more of a state of mind than just a methodology of software development like waterfall.
Scrum is one of the very popular agile methodologies. You can study below aspects of scrum in detail:
Benefits of Scrum/Agile over Waterfall
How can you create better "products" with Scrum/Agile
What are the types of projects better suited for Scrum
Pros and Cons of Scrum
Scrum Rituals and why are they necessary (What advantage do they
bring)
Different roles in scrums and their responsibilities (Scrum Master,
Product Owner and Development Team)
After you have good understanding of working of scrum and its benefits, try to create a pet project.
You will have to play all the roles yourself. You can try to distinguish between what role you are playing currently by wearing different colored hats for each role.
Example:
Product owner : Think from product perspective, what should be the features in the product and why would they be important for your users etc. Then proceed with all the scrum practices.
Scrum Master: Keep checking if you are following all scrum rituals in the right sense and spirit and are you able to derive benefits out of it.
There will be limitations,example you cannot have Daily stand-up meeting, obviously because you are the only person in the project. But if you follow above, you should be good to secure a job and play your part well in the team.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
When you have sprint task in Scrum, where do you put how you want to program something? For example, say I am making a tetris game and I want to build the part of the game that tracks the current score and a high score table. I have my feature, my user story and my task, but now I want to talk about how to design it.
Is that design something that is recorded on the sprint somewhere as to how to do that or is that just somethign the programmer figures out. Do you put do task x use database such and such, create these columns, etc.? If not, do you record that at all? Is that what trac is for? I don't mean too high level design.
I touched on it here: Where in the scrum process is programming architecture discussed?
but my current question is later in the project after the infrastructure. I'm speaking more about the middle now. The actual typing in the code. Some said they decide along the way, some team-leads. Is this is even documented anywhere except in the code itself with docs and comments?
edit: does your boss just say, okay, you do this part, I don't care how?
Thank you.
There can be architectural requirements in addition to user-specified requirements that can muddy this a bit. Thus, one could have a, "You will use MVP on this," that does limit the design a bit.
In my current project, aside from requirements from outside the team, the programmer just figures it out is our standard operating procedure. This can mean crazy things can be done and re-worked later on as not everyone will code something so that the rest of the team can easily use it and change it.
Code, comments and docs cover 99% of where coding details would be found. What's left, if one assumes that wikis are part of docs?
Scrum says absolutely nothing about programming tasks. Up to you to work that out...
Scrum doesn't necessarily have anything explicitly to do with programming - you can use it to organise magazine publication, church administration, museum exhibitions... it's a management technique not explicitly a way of managing software development.
If you do extreme programming inside scrum, you just break your user stories for the iteration down into task cards, pair up and do them.
When I submit tasks to my programming team, the description usually takes the shape of a demo, a description on how the feature is shown in order to be reviewed.
How the task will be implemented is decided when we evaluate the task. The team members split the task in smaller items. If a design is necessary, the team will have to discuss it before being able to split it. If the design is too complex to be done inside this meeting, we will simply create a design task, agile/scrum doesn't force how this should be done (in a wiki, in a doc, in your mind, on a napkin, your choice) aside for saying as little documentation as possible. In most case the design is decided on a spot, after a bit of debate, and the resulting smaller tasks are the description of how things will be done.
Also, sometimes the person doing it will make discoveries along the way that change the design and so, the way to work on it. We may then thrash some cards, make new ones. The key is to be flexible.
You do what you need to do. Avoid designing everything up front, but if there are things you already know will not change, then just capture them. However, corollary to YAGNI is that you don't try to capture too much too soon as the understanding of what is needed will likely change before someone gets to do it.
I think your question sounds more like you should be asking who, not when or where. The reason Agile projects succeed is that they understand that people are part of the process. Agile projects that fail seem to tend to favor doing things according to someone's idea of "the book" and not understanding the people and project they have. If you have one senior team lead and a bunch of junior developers, then maybe the senior should spend more of their time on such details (emphasis on maybe). If you have a bunch of seniors, then leaving these to the individual may be a better idea. I assume you don't have any cross-team considerations. If you do, then hashing out some of the details like DB schema might need to come early if multiple teams depend on it.
If you (as team member) feels the need to talk about design, to so some design brainstorming with other team members, then just do it. About the how, many teams will just use a whiteboard and brain juice for this and keep things lightweight which is a good practice IMHO.
Personally, I don't see much value in writing down every decision and detail in a formalized document, at least not in early project phases. Written documents are very hard to maintain and get deprecated pretty fast. So I tend to prefer face to face communication. Actually, written documents should only be created if they're really going to be used, and in a very short term. This can sound obvious but I've seen several projects very proud of their (obsolete) documentation but without any line of code. That's just ridiculous. In other words, write extensive documentation as late as possible, and only if someone value it (e.g. the product owner).
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
The Mythical Man-Month is now classic, but the "Surgical Team" methodology is still interesting. What methodology most closely resembles it or has the same essence?
To summarize the Surgical Team analogy:
A surgeon understands the problem/business domain and is the expert. They are the authority when there are questions or conflict with in the team. The surgeons work between themselves when there are issues, say with design, functioning as a smaller tight team of experts. So in essence they have the knowledge of the domain, are entrusted to do they think is right, and do the actual coding? The rest of the team focuses on support, testing, documentation, and project plans are delegated tasks. Consequently the surgeon is also the most skilled/trained resource.
The answer could be project, programming, design methodologies as it seems to have implications across main methodology domains. Agile, MDA, Extreme, in sourcing development?
This question also make more sense for software that is large in a complex business domain, think air traffic control, not a COTS developer to or common utility.
One of the patterns mentioned in Organizational Patterns of Agile Software Development is titled "Three to Seven Helpers per Role"; it differs from Surgical Team in that it pays attention to every role, for example it isn't only that the surgeon 'role' that has helpers or relationships: all roles have some number of relationships.
Another pattern from the same source in named "Architect Also Implements", which may be analogous to "Surgical Team" in that the Architect in particular is (presumably) highly skilled.
In the case of a surgeon, the key actor is both the domain expert and the implementor.
I.e., he's both the software program manager (architect) and the developer.
This sort of methodology might fit certain short-burn situations: for instance, a complex operation like a live server migration or software upgrade.
For general development, however, there are a few issues with such "hero" methodologies:
Few key developers understand the problem domain to a sufficient degree, and must rely on domain experts. This is simply a function of specialization--it's tough to find kick-butt programmers who also are lawyers, doctors, accountants, or otherwise are experts in the domain the software is modeling.
Scalability is limited by the number of "surgeons" you have available.
There's a lot of down time for the other staff while they wait on instructions, since the highly-focused "doer" is also managing the team. That's ok in the OR, since you're dealing with a "zero-bug" mandate and "live software." But in this economy, a more distributed workload is more efficient, even if it results in the occasional sync problem between team members.
I'm not sure any methodology really addresses that, as it is really a matter of prioritizing the developers and bending everything to their needs, rather that being anything about how those developers actually develop their software.
If you were looking for some methodolgy that impements this, I suppose this may be bad news. I prefer to consider it good news, in that it means you can use this approach with pretty much any software development methodology.
I've worked on exactly one project that was run that way. It was so enjoyable, I nearly feel bad calling it "work". Four of us developers (with extra support personell, including the occasional extra junior code monkey) got a truly prodigous amount of code written and running properly in only 9 months. Other places I've been couldn't have done as much with a team of 20.
From the text I see the following:
Agile Like:
Small teams focused on solving specific problems
Collaboration among the surgeions
Non Agile Like:
Surgeons are the authority, driving the plan, determining the design, allocating support tasks (viewng them as subservent to coding) and doing the coding. All of those are very command and control in approach and contrary to self directing teams (vs a directed team)
There appears to be no collaboration with the business partner (let alone frequent collaboration with the busines partner)
There appears to be no prioritized product backlog, thus the surgeon picks what is important not the business partner
There appears to be no incrmental delivery (tight feedback loop)
For a waterfall project, it is suggesting to use a team of experts (surgeons) to do the planning, designing, coding etc. and allocating tasks to the "support" staff. On an agile team, testing is not treated as support but an integral part of delivery.
One can't say with certainty the methodology being advocated. However, it does appear to use the language (project plans, tasks) and assume that the waterfall approach is being followed (phases like design, coding, testing driven by a plan). Whatever methodology is being used, it one for which the few determine the work for the many.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this 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).
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.
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?
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 :
Stories come up in the backlog
Story gets picked up by a programmer
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...
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.
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.
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.
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.
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"?