3 ms·

"Working software over comprehensive documentation" "That is, while there is value in the items on the right, we value the items on the left more" I have had

"Working software over comprehensive documentation" "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

Chris_Newton 5y ago
I would be the first to agree that a lot of documentation of little or no value has traditionally been created during software development. I saw an interesting report once about some research on where software developers actually look for information while doing their work. Sure enough, it turns out that some types of documentation are very useful and some are mostly useless, and which is which is very much as you probably expect if you’ve been developing for a while. 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.
- Jtsummers 5y ago
  The kind of comprehensive documentation they were referring to were garbage 1000+ page documents that projects often created listing all requirements, specs, and design elements. In Waterfall and related BDUF approaches the intent was to produce this before any code. A months or years looking effort before even starting… 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.
  - Chris_Newton 5y ago
    The mind of comprehensive documentation they were referring to were garbage 1000+ page documents… 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.

Chris_Newton 5y ago

I would be the first to agree that a lot of documentation of little or no value has traditionally been created during software development. I saw an interesting report once about some research on where software developers actually look for information while doing their work. Sure enough, it turns out that some types of documentation are very useful and some are mostly useless, and which is which is very much as you probably expect if you’ve been developing for a while. 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.

Jtsummers 5y ago
The kind of comprehensive documentation they were referring to were garbage 1000+ page documents that projects often created listing all requirements, specs, and design elements. In Waterfall and related BDUF approaches the intent was to produce this before any code. A months or years looking effort before even starting… 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.
- Chris_Newton 5y ago
  The mind of comprehensive documentation they were referring to were garbage 1000+ page documents… 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.