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