> Working software over comprehensive documentation
> Responding to change over following a plan
These statements from the agile manifesto are directly opposite to any kind of quality software. Documentation and Code Quality are some of the most important features. Your software is not working if it doesn’t exactly match its documentation.
You can live with that in web software, but you’d end in jail if you tried to write security critical systems like that.
Whenever the manifesto says “X over Y,” it does not suggest this is a strict dichotomy. I have worked in an agile manner on software that had extremely well-documented behaviour and all sorts of documented, objective requirements.
The expression "Working software over comprehensive documentation” simply emphasizes what matters at the end of the day: Working software. If you need a certain amount of comprehensive documentation to prove that the software works, you incorporate that documentation into your process.
It’s the same as emphasizing collaboration over contracts. I worked for a decade in consulting, I assure you there are contracts with clients even when you use Scrum. You don’t refuse to have any hard, contracted, binding commitments. It’s just that you prioritize collaborating with people over setting up solitudes that communicate by throwing contracts over a wall.
As for responding to change over following a plan, if you can set up an environment where there are no changes allowed to interfere with the plan, by all means ignore change and follow the plan.
But if you actually have changes that matter, you need to deal with them too. But that doesn’t mean don’t plan, or never follow any plan. It just means, respond to changes that matter.
For example... What if you discover that the security for a piece of software need to be updated. You’d respond to that, wouldn’t you? You wouldn’t push on to finish what was originally planned with your fingers in your ears?
These are guidelines. They’re motivating forces. You are supposed to do it in harmony with the hard requirements of your business and domain.
Documentation can also be useful without working software.
For example, when you have to interface with others. They can work on the software that depends on yours before you have even written a single line of code, and it will work.
Software without documentation also can lead to serious issues – as in the "does the train continue running when the signal is broken" question I mentioned a dozen times now.
In actual critical projects, Documentation over software. The best software is nothing without documentation.
That’s the first point where I have to disagree with it.
In many other points, agile leads to teams just carrying the technical debt with them.
> The best software is nothing without documentation
You know, it’s not enough to restate your own points, you have to read and absorb the things other people are saying.
Once again, “Working software over documentation” does not mean “Working software instead of documentation.”
It means that working software is more important than documentation, but both can be important. And it can be that documentation exists to make the software work.
If I said “Working software over software patterns,” that wouldn’t mean “Never, ever, ever use the Command Pattern, or Adaptors, or a Facade.” It just means that you use those things to make the software work. And if they are essential to making the software work, they are essential.
So you tell me that software is nothing without documentation, and I happen to agree. But software is also nothing without binaries. But that doesn’t mean “binaries over working software.” It just means, “build binaries as part of working software."
Does the fact that you haven't read all the detailed technical specs for your car prevent you from using it? Do you know the detailed specs for the actually critical braking mechanism in your vehicle? Or is it impossible to use your car because you don't know the tolerances of every nut and bolt in the system?
These statements from the agile manifesto are directly opposite to any kind of quality software
No they are not. These statements are guidelines and principles to follow, and are not absolutes.
If the requirements (i.e. acceptance criteria) for features you are working on include comprehensive documentation, then this can be delivered in the context of an agile framework.
You have to document every feature before implementing it, because someone else will write software depending on it while you implement it. If you already document and plan every feature before implementing it, you aren’t doing agile, you’re doing waterfall.
What you are suggesting – to plan, document, implement and test every feature one after another – is just waterfall for every problem separately.
What you are suggesting – to plan, document, implement and test every feature one after another – is just waterfall for every problem separately.
Well, isn't that the core of any software development process? We're ultimately delivering features, and they all require planning, documentation and testing. The development methodology used doesn't change that. 'Agile' is the key word – change will happen, and being agile helps you to respond to that.
I responded to your sibling comment with the definition of Waterfall.
And every single comment defending Agile here was just "well, you can still document stuff before implementing it, and then verify it, and then maintain it". Which, effectively, is: Even if you’re agile, you can still do waterfall.
Obviously I'm not making a particularly convincing argument…
At the end of the day, agile development is primarily about ensuring that you can respond to change quickly and with minimal disruption. Change occurs in all software projects, and agile tries to avoid some of the pitfalls that one can fall into by architecting an entire system in advance.
"Even if you’re agile, you can still do waterfall." is not quite what i'm trying to get across. Rather, it's that agile doesn't mean you can't provide documentation in advance if that is a specific requirement. Bear in mind that external APIs that must be stable are quite distinct from the rest of the system; indeed, it's a horribly design failure if you can't completely swap out your implementation without changing those APIs!
1. You research the actual requirements, including by testing some possible alternatives via mockups, etc.
2. You design the concept of your system, design APIs and interfaces.
3. You implement it.
4. You verify it matches the design and fulfills the requirements
5. You release it and maintain it.
Most importantly, after Step 2 your APIs don’t change anymore. This is especially important as third parties might rely on them.
I appreciate that's the definition, but the problem that agile tries to deal with is that this almost never happens as you describe in practice.
In reality:
1. You research the actual requirements
2. You design the concept of your system, design APIs and interfaces.
3. You implement it.
4. You discover that the requirements are unimplementable because of some unforeseen design issue
5. You make changes to your implementation, documentation and requirements to deal with this
6. You discover that documentation regarding a third-party system is inaccurate and requires design changes
7. You make changes to your implementation, documentation and requirements to deal with this
8. You verify it matches the design
9. You discover previously unknown acceptance requirements
10. You make changes to your implementation… and so on.
??. You release it and maintain it
Even with skilled, competent developers and architects, no system ever turns out exactly as expected. The goal of agile development is to accept that and try to incorporate the concept of continuous delivery and adaptation into the core of the process – since it's required anyway!
I think you missed my point there – I'm not describing an ideal agile process. It doesn't matter how many proof-of-concepts, mockups, tests and design documents you produce in advance. Change still happens.
Matthew already highlighted the concerns. So, hypothetically, what happens when just after you finish step 3 it is found that one of the core security mechanisms that the security of your life-critical product depends on and that was part of your published API is suddenly found to be insecure due to some new breakthrough in a research lab somewhere? Do you throw it all away and start over from step 1?
Or what happens when, again at step 3, you discover that one of he approaches advocated by the design, and tested by the mockup in the small is unacceptably non-performant when scaled to the real load? Or some other constraint that was not fully tested by the mockups?
You can't say "well, we do a better job with the mockups." If the mockups covered 100% of the functionality and requirements of he system they wouldn't be mockups, they would be the product.
And if your answer is, "well we do this kind of discovery in the testing and mockup phase, changing the mockups to reflect the issues we encounter," congratulations, you are doing Agile development.
I'm not sure how a 'waterfall'-style development lifecycle will help you here. Even if you front load all of your design, documentation and implementation, you will still find bugs and security flaws in your software. As an example, see every software product ever shipped!
I think you're maybe labouring under a misapprehension of what agile development means. In particular, you don't have to 'constantly update' deployed software in order to be able to develop in an agile fashion. You're free to follow the guiding principles to make sure you are able to cope with changes when they inevitably happen.
> That is, while there is value in the items on
the right, we value the items on the left more.
Agile does not say that documentation is not important, nor does it say that a plan is bad. Documentation is worthless if the software doesn't work. The plan is crap if it no longer addresses the actual real-world requirements of the product.
A software without perfect documentation is worthless.
Without documentation, you have to assume things. Does the train, if the signal is broken, stop or continue running? Does the radiation treatment machine, if you have a race condition, and two commands are executed at the same time, block, or just execute the last command?
> Documentation and Code Quality are some of the most important features.
Code quality is an important attribute, sure, but those don't say anything about it.
Comprehensive documentation of the bureaucratic sort of process documentation that I think motivated that line is not a deliverable, its an artifact of process; when it becomes understood as an end to its own rather than as something that should be used to the extent it is useful to achieve value in the end product, it becomes extremely problematic (I've experienced the kind of bureaucratic software development that this reacts to, and I can assure you that it does not contribute positively to quality, it contributes to management -- and staff -- spending lots of time worrying about and measuring and optimizing metrics that are unrelated to quality.)
> Your software is not working if it doesn’t exactly match its documentation.
Your software is not working if it doesn't deliver the expected behavior. Documentation of requirements is important to provide a consistent method of communicating between people (and across time and space) what those expectations are. And to the extent that it is necessary for that purpose documentation is a good thing.
But its important to keep the purpose in mind. Otherwise, you end up with excessive effort going into polishing documentation rather than building software.
> you’d end in jail if you tried to write security critical systems like that.
Sure, bureaucratically comprehensive documentation is extremely useful (and sometimes essential) for demonstrating compliance with process mandates. Such mandates, and the incentives they create, are also very often not helpful to the actual quality of software, including the aspects of software quality which motivate the mandates.
I’ve worked on some agile projects from others that I picked up and had to "fix", where we, now, after 2 years of trying to work with them, have decided to completely rewrite them from scratch.
Every agile project I’ve seen yet was just a huge ball of technical debt. It worked, it had few user-facing bugs, but adding features was impossible, and the documentation was "whatever the software does". Completely matched the agile manifesto "working software over documentation" and "change over plan".
Your response is selection bias. Every project that you've seen is a ball of technical debt. There is no argument to how documentation alleviates technical debt. If you document a poorly designed and scoped piece of software it doesn't make it any easier to change.
If the software was impossible to change and that change was a requirement then the code bases you were working with did not represent "working software"
The agile manifesto says, "working software over documentation." It does not say "working software and an absence of documentation."
The fact that you needed to add features is exactly the reason agile exists. If the creators had a complete feature plan in the beginning and faithfully executed it without deviation from the plan then there would be no need to ever add features and the quality of the code in terms of "changability" would be moot.
As compared to the waterfall projects I've witnessed, most of which never made it to completion, the rest of which were far away from what the client actually wanted once delivered.
Unfortunately, outside of a small percentage of companies, most software written today is just bad.
"Your software is not working if it doesn’t exactly match its documentation."
Not true. Documentation is not always updated. And many times, if not every time, the requirements documents the clients give are often flat out wrong. So you could build the software to the requirements, and end up with something that doesn't meet the client's needs.
"Documentation and Code Quality are some of the most important features."
However, these take a backseat to working software.
Your software is not working if all the third party services that depend on the API you provide are broken because you changed your API, or because your documentation is wrong.
You can work without documentation or without stable implementations if you control all the endpoints and ensure they always have the latest version (like mobile apps, web apps, etc). But if you can’t, you have to remember that every API version you’ll ever provide will have software using it, and you won’t be able to EOL the support for that version.
> Responding to change over following a plan
These statements from the agile manifesto are directly opposite to any kind of quality software. Documentation and Code Quality are some of the most important features. Your software is not working if it doesn’t exactly match its documentation.
You can live with that in web software, but you’d end in jail if you tried to write security critical systems like that.