Short answer: iterative prototypes.

Long answer: I have yet to see a single project in all my decades of experience in this industry where the requirements didn't change during the project. A "comprehensive requirements spec" is and always was a myth. Agile wasn't even the first to say this bit out loud. Software is always developed by a series of iterative prototypes, only sometimes does the process acknowledge this.

Lots of retroactive changing of gantt charts, too :)

OK, but then how do you know what each prototype is required to do?

It’s true that you might be lucky enough to work on a project where your employer/client/customer is willing to let you make some of the decisions. In that case, you are effectively defining some of the requirements yourself and hoping that your employer/client/customer will be happy with your decisions. That’s a risk you can mutually agree to take, and sometimes it will pay off royally, and sometimes it will end in disaster, and probably most of the time it will end somewhere in between.

However, in my experience, the more important the software you’re building is, the less likely it is that you will have that kind of flexibility for the developers. At the extreme end of the industry, if you’re building something like the control system for medical equipment that will kill the patient if it goes wrong or a billion dollar satellite that you get one shot at launching, you probably aren’t going to be doing it through informal discussions with a “product owner” and relying on TDD to make sure everything is working (where “working” in that case is really a euphemism for “whatever test conditions an individual developer felt might matter”).

I have yet to see a single project in all my decades of experience in this industry where the requirements didn't change during the project.

Of course, but every time the requirements change, you still need to identify what the change is so you can change your implementation accordingly. There are many ways you can address that problem, some of which involve one big requirements spec document and some of which don’t, but if you don’t end up with some clear and well-maintained spec each time, you don’t know what you’re trying to build and you have no meaningful definition of “working software”.

For most projects, both "knowing what to build" and "working software" will never be 100% clear.

You define an area of exploration for each prototype. Like "we think that the hard part of this problem is getting the encryption right, so we're going to explore that in this prototype".

And I thought SpaceX disproved this whole waterfall approach to rocket science? They have used iterative prototypes to build better rockets considerably faster than the waterfall approach used by the rest of the industry.

My argument is that whatever stage you’re at in your development process, if you don’t have clear requirements, you don’t know what you’re trying to build and you have no way to define whether your software is working or not. The comparison from the Agile Manifesto makes little sense, because having comprehensive documentation of your requirements and acceptance criteria is a prerequisite for even being able to define the working software that the Manifesto says is more valuable.

Of course you might do all kinds of prototypes and proofs-of-concept to help you explore the problem space and clarify the requirements in the early stages of your project, and maybe again later if there are significant changes. But this work isn’t about building working software, because you don’t know what that means yet; it’s about doing experiments to help you find out.

Providing the customer with a working prototype to criticise often (always) allows them to refine their vision of what they wanted and helps them communicate what they need. It's always easier to criticise something than create - saying "the interaction around X doesn't feel right, can we make it cornflower blue?" is a lot easier than "the X interaction must be three shades of grey off cornflower blue" in a spec document.

That's been my experience, anyway. Insisting on a comprehensive spec at the start has always been more effort than its worth, because no-one knows what they actually want at the start.

In the case you’re talking about, creating a prototype and then soliciting feedback from the client might be an excellent way to go. More generally, building a project in stages with regular interaction with and feedback from the customer or other stakeholders is often helpful. My point is that you still need to decide what you’re putting in that prototype or any of those earlier stages, because ultimately some developer has to write that code and management need to tell them what to create.

So you might well have a spec, in whatever form, that has initially has gaps or ambiguities relative to the final product you’ll want at the end of the whole process. That’s fine, and as you say, it is very common. But it should still reflect everything you know you want at the current time.

If and when you gain new information, such as feedback from your client after showing them a prototype, you can update your requirements to fill in the gaps or clarify the ambiguities in light of the additional knowledge you now have. You still have a clear record of what is needed, taking into account all the actual decisions that have been made and all the actual feedback you’ve received, and that is (to the best of your knowledge at that time) what defines whether or not you currently have working software.

Put another way, if you don’t maintain a good record of that information, you’re just building your software based on hearsay. Some of that information about what the customer/stakeholder actually wants will inevitably be lost or distorted with the passage of time and perhaps the changing make-up of your team. And then you definitely don’t have working software, whether or not you realise it.

"That is, while there is value in the items on the right, we value the items on the left more"

I have had many discussions with both agilest and let's say traditionalist about these statements. funnily enough people from both "sides" sometimes mis interpet (or at least that is my view) the statement as; agile means no documentation. To me it is about just enough documentation. You should know what needs to be build, what you expect from it etc.

But in the end it is better to have working software than to have piles of documentation. So there is value is having documentation but the end goal is working software.

If you are old enough you remember months and sometimes years spend at documentation, scribbling over details, etc. At the end of the documentation phase they started building, than a building phase that could take months or years. After the building phase they found out the things that seemed handy at the time where not working in real life or where obsoleet. So a analyst should create a RFC which again would take lots of time before it would finally be made

The idea of having working software over comprehensive documentation is that it is better to start building the most important feature(s) and release it as soon as possible. This makes sure you add value as soon as possible. Documentation by it self doesn't add value, but working software does. This doesn't mean that the important feature should not be documented, but it should be documented enough to add value as quickly as possible. That way you get feedback from the users and change what is needed instead of talking for days about what something should do and what problems might arise from some theoretically edge case. Also it makes prioritisation much easier. Maybe an edge case can be tackled by a change of process in state of a difficult software solution. thus having time to work on a feature that adds more value

Still, when it comes to things like defining the requirements and acceptance criteria for software, “just enough documentation” and “comprehensive documentation” are often the same. Otherwise, you literally don’t know what you’re trying to build. That is not to say that you have to have one big requirements spec that never changes (or one big set of requirements specs including numerous cross-references, if it’s that kind of project) or that every change must go through an extensive change management process involving 27 people and a month-long delay to fix a spelling mistake in the original spec. But you need something that clearly defines what the software is supposed to be.

As I noted in another comment, if you are making software without that, you don’t really have a useful definition of “working software” to prefer. Obviously you can still go ahead and make something. It’s just that both sides are then taking on the risk that the development team’s assumed requirements when they fill in the gaps will be satisfactory to whoever is paying the bill. That could end anywhere from spectacularly successful to a dismal failure, which doesn’t seem like an ideal basis for a software development process to me. Perhaps a more common scenario, particularly for software developed in-house or outsourced on a T&M charging basis, is that when differences arise you go back and correct them afterwards, so you still get what the end customer needs but it takes longer and costs more than was really necessary to get there. This is a more insidious danger, because if things do work out in the end, you might not have any quantifiable way to assess what you lost or maybe any awareness that you lost out at all. But you still lost out all the same.

The idea of having working software over comprehensive documentation is that it is better to start building the most important feature(s) and release it as soon as possible. This makes sure you add value as soon as possible.

Sometimes. It depends entirely on your situation. Shipping a line-of-business application with 75% of the desired functionality that you can then incrementally develop further in production might offer a lot more than 75% of the value. Shipping 50% of the software that controls the mechanics of a modern car might offer 0% of the value, and if shipping that 50% early means the 100% point when the car is actually useable is delayed then doing so actually has negative value, and the only early feedback you’re going to get is that no-one has bought the car yet.

If you work in an old school environment where you get work packages and you just have to do the work. You will need more documentation. simply because you can't ask any questions to the requestor.

Value is not only measured at the end of a total delivery. So for instance your car example. It could be really valuable to deliver the ABS part of the software to test it and any other safety and control functions. All these functions can get tested before the whole is delivered. If some less important features might not make it in time before the car launch you could decide to bring the car to market with the most important features and add the farting feature with an OTA update

Sure, though can we please not pretend that Agile introduced the concepts of talking to other people between the start of a project and delivery or of trying to get everyone involved on the same page?

If you have shared understanding, that is to say everyone understands the end goal it is easier to have less documentation.

But how do you know that everyone really does understand the end goal, and crucially understand it the same way, if you haven’t fully defined what that goal is? If you have fully defined it, great, you have a spec.

If you work in an old school environment where you get work packages and you just have to do the work. You will need more documentation. simply because you can't ask any questions to the requestor.

Has any such environment actually existed since before most of us were born, though? This seems like the big waterfall straw man again.

Value is not only measured at the end of a total delivery.

Agreed.

So for instance your car example. It could be really valuable to deliver the ABS part of the software to test it and any other safety and control functions.

Yes, it could. Then again, modern car control software integrates numerous effects that determine the actual response required from different mechanical components to driver inputs and environmental factors, of which ABS is just one case. What ultimately matters is that the overall system is working properly by the time the car is ready to drive, and everything else is a stepping stone towards that end goal.

If building incrementally and working on the ABS in isolation allows for early testing and feedback and that in turn allows for more efficient correction of any defects in the original implementation, yes, absolutely, that has value.

On the other hand, if that kind of isolation and early testing is unlikely to find important defects in the finished system, perhaps because it turns out that the way you build individual systems is fairly reliable and the defects mostly arise when integrating the different systems, and if building everything in isolation and then integrating later delays your overall progress and the time when you can start the integration testing, then the more isolated approach has actually cost time and money rather than saving it.

I want to emphasize that my point here isn’t about this specific example. It is that every software project has its own context and it is important to use a development process appropriate in each context. Sometimes, it’s OK to guess at what your software should do and see if it works out. The kinds of startups we talk about all the time on HN often do this, obviously with varying degrees of success. But I think we should recognise that the whole business model in that case is essentially built around permanent experimentation and high variability outcomes. It’s not a way to build better software as most of us might define the term. It’s a strategy of throwing stuff at the wall to see what sticks, which happens to be a commercially viable strategy for some businesses in the current economic environment, where the definition of “working software” is basically “software we can run that will make us enough money to continue”. Somehow, I doubt that is what the authors of the Agile Manifesto had in mind when they wrote that line.

Sadly I have seen work packages delivered to software teams without any context just specs. Sadly I have worked and seen projects that went down the documentation rabbit hole and spend years trying to come up with the ideal spec before any thing has been build. (and I'm not even that old). You would see that kind of stuff with in government but also large enterprise and even at mid sized companies. And it still exists today

I also have seen successful waterfall projects and I have seen failed agile projects (although those tent to fail faster and thus less costly)

The agile way is not the only way, there are instances that other ways of working might be better.

But for me personally the best work experiences where all companies that worked agile or where transitioning to agile. I worked this way (and helped in the transition) at companies ranging from scale ups to big enterprise.

A many a time I have had these same discussions with people at the beginning of a transition. Mostly people that never worked this way or had a bad experience.

My original comment on the Agile Manifesto, which seems to have attracted most of the responses I’ve read here today, was only intended to make the point that without knowing what you’re trying to build, you have no way to define whether or not you have succeeded. I therefore don’t think it makes much sense to talk about valuing working software over comprehensive documentation in general terms as the Manifesto does. You can only know your software is working to the extent that you know how it’s supposed to work in the first place.

The Manifesto is pretty explicit that “over” in the “over” statements means exactly what it says, and isn't a misspelling of “instead of”; the Manifesto very much does not claim that there isn't some degree of documentation that serves an essential role in defining and achieving correctly-functioning software and that that isn't instrumentally important.

I do wish, though, that rather than “over” statements with an explanation that “over” means “over” and not something else the manifesto had used something like “is/are served by” in place of “over” (with some light editing of the items on the sides to fit that structure):

  Individuals and interactions *are served by* processes and tools.

  Working software *is served by* appropriate documentation.

  Customer collaboration *is served by* contract structure.

  Ability to respond to change *is served by* planning.

like I said in the beginning of the discussing the manifesto reverenced to those type of environments.

The point in the manifesto is to get to just enough (which is usually not 1000s of pages) and then start coding. Not to skip it entirely. The other issue with those documents form my experience was that unless it was a replacement of an existing system, the documents were wrong every time. And you’d lose more months fixing them or just continue to diverge and let them lie.

Re: your last paragraph. We’ve done that for aircraft. Ship a 50-80% solution that gets you into flight test instead of waiting for 100%. Then finish it over the next months or years. It’s very effective. You just have to be smart enough to identify what is the MVP.

Perhaps, but I don’t believe that is how the documentation point in the Manifesto has always been interpreted since then, and I suspect no-one else here does either.

As I said in my original comment, I think the ideas around Agile can be an interesting and useful area for discussion, but I’ve never fully agreed with the Agile Manifesto as-written. The danger with making these kinds of short, profound statements about a field as nuanced as software development is always that you immediately have to start backtracking and clarifying that what you really meant was… And as soon as you’re doing that, probably the original statement has lost most of any value it might have had anyway and it’s more interesting and productive to discuss the nuanced issues that you brought up afterwards instead.

In Waterfall and related BDUF approaches the intent was to produce this before any code.

OK, but it’s not as if everyone was trying to write software that way before the Agile Manifesto came along. I’ve been writing software for money since well before the Manifesto was published, I’d say I’ve worked on a fairly broad range of applications over the years, and I don’t think I’ve ever seen that kind of process in actual use either before or since the publication. Waterfall just seems to be the preferred straw man for Agile advocacy.

You just have to be smart enough to identify what is the MVP.

Or, more generally, you have to be smart enough to identify which milestones in terms of functionality and performance add real business value. That is almost always some kind of step function. Reaching an MVP that you can deploy to start collecting feedback from end users on a realistic product and ideally bringing in some revenue as well is obviously one of the more important steps when developing certain kinds of software, but really there is nothing unique about it and even for those kinds of software the same principles apply both before and after shipping the MVP.

That then invites the question, how do we identify what we need to have ready before we take the next step, MVP or otherwise? And just like before, the options are essentially to check our requirements or to wing it and hope that we’ve guessed well.

People keep saying this, but either I hallucinated the early part of my career, or it's real. The straw man is saying that it's a straw man.

I've seen Waterfall used on other projects since then including a major information system that resulted in about $1 billion of waste, fortunately I've only been adjacent to them not on them. The billion dollar waste relied on (as Waterfall often does) late integration, none of the pieces worked together even though everyone built everything per the spec they'd been given.

If you've not encountered it, that's great. Doesn't mean it doesn't exist.

The issue I have always had here is that in order to go fast and have short cycle times you need quite a bit of automation and the more you rely on automation and make it work the easier it is to maintain iterative agile development. That requires processes and tools maintained and the more you rely on individual personal preferences and nuances the longer those cycle times will be.

Once you get down to continuous delivery you don't have much choice but to have automated tests written for everything, the basis of which might have been a fantastic interaction with a stackholder with a good back and forth on the right tests, but its far too reductive to just always value people over process when solid engineering is critical to low cycle time for software agility.

It seems the manifesto was written from a contract interaction perspective for consultants. With the product mindset however these types of scenarios are a lot less common but the engineering doesn't go away. Its just one aspect that has annoyed me where Xtreme programming got more into defining what a good project actually ought to be able to do and the sort of processes that were necessary to make it work even if some of it was flawed it hung together better than a set of values.

Yes, agree here.

> I do think the early Agile advocacy served a useful purpose..

Agree.