DEV Community

Cover image for Should Agile Manifesto be revised?

Should Agile Manifesto be revised?

Alex Pushkarev on September 15, 2022

Is there premise in the manifesto you would disagree with? The biggest problem with it that I see is this one: "Working software over comprehensiv...
Collapse
 
mcsee profile image
Maxi Contieri

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

Collapse
 
jmfayard profile image
Jean-Michel πŸ•΅πŸ»β€β™‚οΈ Fayard • Edited

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.

Collapse
 
dadyasasha profile image
Alex Pushkarev

Very good and detailed explanation, thank you!

Collapse
 
mcsee profile image
Maxi Contieri

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

Thread Thread
 
jmfayard profile image
Jean-Michel πŸ•΅πŸ»β€β™‚οΈ Fayard • Edited

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.

Thread Thread
 
dadyasasha profile image
Alex Pushkarev

awesome point. I would say that quite a big chunk of software (maybe even most of it?) is meaningless w/o documentation

Thread Thread
 
mcsee profile image
Maxi Contieri

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.

Thread Thread
 
jmfayard profile image
Jean-Michel πŸ•΅πŸ»β€β™‚οΈ Fayard • Edited

Without dead poetry:

  • nobody knows that your software exist
  • nobody understands why they should care
  • nobody understands how to get started with it
  • nobody understands how to use it for non basic stuff
  • nobody knows how to troubleshoot it when something doesn't work

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.

Thread Thread
 
dadyasasha profile image
Alex Pushkarev

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!

Thread Thread
 
pinotattari profile image
Riccardo Bernardini

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

Thread Thread
 
jmfayard profile image
Jean-Michel πŸ•΅πŸ»β€β™‚οΈ Fayard • Edited

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

Thread Thread
 
darlanalves profile image
Darlan Alves

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.

Thread Thread
 
dadyasasha profile image
Alex Pushkarev

very good example - thank you for sharing!

Collapse
 
tqbit profile image
tq-bit

The statement "Working software over comprehensive documentation" for me means:

There's no need to write documentation if the software doesn't work

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.

Collapse
 
dadyasasha profile image
Alex Pushkarev

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?

Collapse
 
tqbit profile image
tq-bit

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:

  • They get a well-paid agile coach to install 'an agile process'
  • Coach holds 3 months worth of workshops, leaves.
  • People who worked their whole life in waterfall are happy, but confused.
  • They're "empowered" to work as they like, but still receive unidirectional orders from their superior.
  • Enthusiastic manager starts holding 'sprint meetings'. Which are basically the same meetings as before.
  • The result: An agile(?) waterfall. In fact, more waterfall than agile.

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:

Build projects around motivated individuals.
Give them the environment and support they need,
and trust them to get the job done.

The rest will sort itself out somehow.

Thread Thread
 
dadyasasha profile image
Alex Pushkarev

OK, but what if we don't have access to motivated individuals and there's no time to build the environment?

Thread Thread
 
tqbit profile image
tq-bit

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.

  • Talented people pool at 'good' companies
  • These care enough to trust and value their employees
  • The individuals then build the environment they wish to have
  • Which in turn attracts more talented people, and so forth
Collapse
 
atimin profile image
Alexey Timin

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.

Collapse
 
dadyasasha profile image
Alex Pushkarev

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.

Collapse
 
tandrieu profile image
Thibaut Andrieu

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

Collapse
 
dadyasasha profile image
Alex Pushkarev

That's why I am thinking it should be revised - clearly w/o additional clarification the message is very easy to misunderstand

Collapse
 
lexlohr profile image
Alex Lohr

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.

Collapse
 
dadyasasha profile image
Alex Pushkarev

I really like your perspective, thanks for sharing

Collapse
 
eljayadobe profile image
Eljay-Adobe • Edited

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.

Collapse
 
webbureaucrat profile image
webbureaucrat

software is only part the product. Arguably, it is not the most important part of the product as well.

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.

Collapse
 
dadyasasha profile image
Alex Pushkarev

That's why I am thinking it should be revised - clearly w/o additional clarification the message is very easy to misunderstand

Collapse
 
docsbydesign profile image
Bob Watson

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.

Collapse
 
mattmoranjava profile image
Matt Moran

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.