Is there premise in the manifesto you would disagree with?
The biggest problem with it that I see is this one: "Working software over comprehensive documentation". It sounds good, it is also a very convenient premise to believe in - many developers hate writing documentation. But I it think misses an important part of the problem - software is only part the product. Arguably, it is not the most important part of the product as well. If we can solve a problem without writing any software, for example by updating the documentation - everyone would win.
If a user cannot use the software or software does not solve user problem - it doesn't matter if it is working or not.
As an extreme and somewhat sobering example, lets consider Boing Max disaster.
Boing Max had the capabilities to overrun faulty autopilot commands, but because it was never properly communicated in the manuals pilots could not use the functionality. Mostlikely they even didn't understand its significance. The decision to compromise on a documentation part resulted in 3 planes crashing, killing hundreds of people.
It seems that Manifest was designed for a particular point of time and a particular environment and wasn't supposed (or ready) to be universally adopted.
What do you think?
Top comments (29)
Documentation is dead and it lies.
Use cases automated are alive and maintained
You want documentation for your customers?
Send them your tests. Not dead poetry
Manifest is accurate
Agile is the problem
Counter argument: written communication is in fact not always but often very efficient.
Actually the whole modern civilization is based on that. So it's quite a bold claim to affirm the contrary and I don't see your extraordinary evidence that should come with it.
Your Software doesn't lie?
That sounds impressive, I would like to know how you do that.
Despite years of experiences, I still write code with bugs all the time.
Often the tests pass, but the tests don't actually test anything meaningful.
Or simply they lack lots of things I didn't anticipate.
Or both the test and the code may be right, but still they make no business sense.
How should I know whether what I wrote make busines sense?
I read documentation written by others.
Asking the same question again and again is not efficient.
So code lies all the time.
But you say that when the code lies, you can maintain it.
How is this different from documentation then?
The real question is whether it's easier to maintain documentation or software?
Have a look at how well Wikipedia is maintained versus the average open source project on GitHub
It's pretty clear than in average it's easier to maintain documentation.
Send customers your tests?
No thank you, I don't want to read Forem's test to know what liquid tags are available.
I think you would hate it if professionals from any other industry would have the same attitude.
Very good and detailed explanation, thank you!
If the tests don't exercise anything meaningful the problem is on the tests quality. Not the documentation
If the tests don't anticipate is a good symptom we are learning the domain.
Software is about learning
Code speaks truth about the current knowledge we have.
Documentation lies the minute it is written down since nobody ever maintains it
I sent the use cases to my customers. Never the documentation
Humans learn from examples
Don't get me wrong, I like both testing and documentation. Given the use case I will favor one over the other.
But your double standards do not make sense.
In practice most people don't test correctly and most people don't document correctly.
In the first case you say tests are good per se, it is people that are just doing it wrong. They should work on their testing skills.
In the latter case you say that's inherent to written documentation, there's nothing we can do to improve our writing skills to make documentation more useful.
Good tests exist and can be amazingly useful.
Good documentation exist and are amazingly useful.
For example I'm a backend developer, which in practice means everything I do looks ugly because I can't for the life of me understand CSS.
But I can understand tailwind css.
Why? Because its documentation is amazing tailwindcss.com/docs/installation
Tldr:
It would be more honest to simply admit that you are more skilled and comfortable with testing than with writing.
awesome point. I would say that quite a big chunk of software (maybe even most of it?) is meaningless w/o documentation
We should try our best to cover this software
With documentation we have useless dead words.
With tests we can ensure we can refactor and make it evolve.
Without dead poetry:
In short you have great code, well tested but that absolutely doesn't matter.
At least that's my experience as an open source maintainer.
I agree with @jmfayard . Testing and evolving software are orthogonal concerns to the documentation. If software is of no use because nobody knows how it does not matter if is easy to change. You might as well delete it straight away and nothing will change.
Bonus part here - non-existent software usually have no bugs w/o ever needed to be tested!
"Humans learn from examples"
That is not always true, at least not for me.
Personal example: I am currently learning (for my own fun) to use blender, the 3D modelling program. Blender is quite a complex piece of software and there is no hope that you can learn it by wandering around, at least if you are not a 3D designer with many years of experience.
If you go on YouTube you find an humongous amount of tutorial that try to "teach by example." The script is always the same
"Oh, let's do an ashtray! (say)"
"Remove the initial cube"
"Shift-a and add this"
"Click here and there"
"Do this and that"
"Pronto! Here it is your ashtray"
After watching that video you can do an ashtray (maybe, if you rewind it and follow the instruction), but nor much else. You got an example of use, a use case that tells you nothing about the "model" behind blender, why you cut the cylinder in half and then recreated the missing half with a ... "modifier". What is a modifier? Why deleting half stuff to recreate it later?
This example teaches me nothing.
There is a good channel of blender tutorials (Blender Guru) that has a different approach. It looks the same, but it is subtly different. He uses a "use case" (his donut is quite famous) as an example to illustrate the concepts in blender. After watching a video of his you do not just learn how to do a donut, but you learn also, say, what a modifier is, why you want to use it, what a "loop knife" and why it is useful, what a geometry node is, and so on...
After watching a video of his you can fire up your project and apply what you learned to it.
You would say that it is not written documentation, but visual. This is true, but it is also the nature of the program (a 3D graphic modeller) that makes the visual media especially efficient. You could write a textual tutorial based on Blender Guru videos and they would had been equally effective.
Really good point.
I exactly had the same experience with learning to record music.
I was completely until I took the time to learn the concepts.
The same works for written documentation as well, this great article being a prime example
Learn git concepts, not commands
Nico Riedmann γ» Jun 2 '19 γ» 36 min read
To also illustrate the points here: take Angular.js and its documentation back in 1.0.x days... The docs were so bad that the only way yo understand them fully was to read the source.
There were plenty of tests, but is was not realistic to expect a developer to read their tests to understand how to use a framework.
Everyone was hyped with the new tool, but the learning curve was damn steep.
Then Angular came along to fix many of these issues, and it not only has a great cli, but also extensive documentation. And there's no need for reading code most of the time.
Tests are essential, but they are not meant for people outside the team actually writing code.
That's what documentation is for.
very good example - thank you for sharing!
The statement "Working software over comprehensive documentation" for me means:
This does not set the developer team free of writing docs. And I find tests to be complementing parts of the documentation.
To answer your question: I don't really disagree with anything about the agile manifesto. I disagree with how it's being used by people who try to adopt an agile style without at least trying to adopt agile culture.
That maybe what has to be addessed - I think in average with the current wording of the manifesto there're very good chances it will be misinterpreted. Should we change the wording to decrease the chance of it happening?
I'm not sure if a change in wording will be the ultimate solution.
What really is necessary is to emphasize that agile PM is fundamentally different from waterfall PM. Where the former emphasizes the final product and its stakeholders, including the dev team, the latter puts the process(es) over pretty much everything else.
What I figured happens in companies is the following:
I'm being overdramatic, but you'll catch the core message.
Anyway, if you'd like to change anything about the agile manifesto, I'd say is make the following its headline:
The rest will sort itself out somehow.
OK, but what if we don't have access to motivated individuals and there's no time to build the environment?
Then you regularly play your national anthem and make your co workers goose step through their working day.
There are some companies that aren't (and shouldn't be) agile. Do you think your plumber takes part in sprint artefacts? They arrive, do their job and leave.
With development, that's a different story. Until it isn't. As a motivated individual, it's up to you to know the difference. And when it's time to leave for a company that's capable of implementing an agile culture.
Which - again - after some time will sort itself out.
I guess it is about documentation to create future software but not describe already existing one. The idea was to create something working in very begging and start learning. So I would replace "documentation" with "specification" to avoid misunderstanding.
that would make sense. The other way to put it would be "planning", which indeed may be very unhelpful. That what I meant by revising.
I have always understood the term "Documentation" here not as "The software user manual", but as "The project documentation".
For me, it more refer to the old V-Cycle or Waterfall model, where every single step, every single use case, every single constrains should be clearly specified and documented before writing a single line of code. And in the end, project managers use to hide themselves behind exhaustive specifications to justify they did a good job, whatever the result of the product at the end.
So I tend to translate this phrase by "Working software over exhaustive Jira".
That's why I am thinking it should be revised - clearly w/o additional clarification the message is very easy to misunderstand
I think the whole agile manifesto glosses over a core problem: software development is often messy and unpredictable. No process, regardless how well-intentioned and -implemented it might be, is going to change that.
Managers want to ship features fast, which requires them to take less time, developers want to deliver quality code, which requires them to take more time. The agile manifesto attempts to resolve this conflict by suggesting that face-to-face interaction would lead to.compromises. In most cases, it doesn't.
I really like your perspective, thanks for sharing
The authors and signatories of the original Manifesto for Agile Software Development would unanimously say "YES!"
Not because it is bad. Only in that it was a snapshot of their collective experience at the time. It was not intended to be written on stone tablets. A response to the "state of the industry", circa 2001.
It was (and is) expected that the principles and values expressed therein do and will evolve.
I think you're using the word "documentation" differently than it is used in the manifesto. User (or calling code) documentation is a necessary part of software products, but I think the manifesto refers to maintainer docs.
The reason why working software is more important than maintainer docs is that if the software isn't working, then the maintainer docs are communicating something that isn't true, whereas if the maintainer docs are incomplete but the software is working, then at least the maintainer can read the code.
That's why I am thinking it should be revised - clearly w/o additional clarification the message is very easy to misunderstand
When the Agile Manifesto came out, I read that one as:
βWorking software over comprehensive [design] documentation.β
But, itβs generally been interpreted as:
βWorking software over [any] documentation[, design or otherwise].β
Which is impossibly impractical.
The software should document itself, but I am a big fan of documenting all the business decisions that were made to get the software to its current state, and any that are made to alter or extend it after release. The test suites should relate to business decisions - JIRA tickets for example, which would be kept as a permanent legal record of the project.