Comment by GuB-42 | Hacker News Reader

Comment by GuB-42 | Hacker News Reader

Parent Full thread

> There is nothing in agile stopping you from producing comprehensive designs or specs.

Agile manifesto, 2nd point "Working software over comprehensive documentation".

It certainly doesn't stop you but if you focus on writing comprehensive documentation before working software, it is not Agile, it is something else.

As for Agile offering "protection", maybe I misunderstand your point but for me, Agile is the opposite of protection. I think that if there is one thing that defines Agile, it is that the customer is very close the the team, so it can be, well, agile. The customer has to be there to see how things are going and adjust course as necessary, unlike the waterfall style where a formal contract protects both the team and customer.

Note that I don't consider "waterfall" bad, and "Agile" good. It is just different approaches for different situations. If the customer wants an "hands off" approach, or if you write certified software, then I believe that "waterfall" style approaches are superior most of the times.

> Agile manifesto, 2nd point "Working software over comprehensive documentation".

Isn't the 0'th point that agile still values the stuff on the right, it just values the stuff on the left more?

OP's opening statement was a little off. What OP went on to describe was not "comprehensive documentation" in the Agile sense but merely "documenting progress and learnings as to not repeat mistakes". The "comprehensive documentation" in Agile is trying to avoid the "We have delivered exactly what you asked for even it if is no longer what you need."

Regarding documentation, my team tends to choose parts of a project to document in detail before the project begins. These are usually around requirements and dependencies that have a low likelihood of changing. But throughout the project, the product is the gospel and the docs evolve towards that until delivery.

I suppose if you did a pre-planning phase like ours but comprehensively documented your entire product and then delivered exactly to those docs 8 months later without input, you'd not be doing agile for sure.

When I say protection, I don't mean protection from the customer. The scrum process protects the team by requiring the ICs on the dev team to choose the user stories or work items which will come into the sprint. This prevents management from committing the team to work they themselves do not think can be accomplished. This meeting should leave a written record which is shield but also the acccountability for the dev team.

> Agile manifesto, 2nd point "Working software over comprehensive documentation".

Which is funny given that the father of TDD, Kent Beck, is one of the Agile Manifesto signatories. What does TDD give you before working software? Comprehensive documentation.

TDD doesn't give you documentation, it gives you tests. Typically automatic unit tests, which is code.

Tests serve a different purpose. They are not for humans to read, they are to make sure your software works ("working software"). They are an important component of Agile because it makes it easier to change your code without breaking things.

Now, I am not big into TDD, but for me, it is an approach that is fully compatible with the Agile manifesto.

> TDD doesn't give you documentation, it gives you tests

Test is the action that is carried out from the documentation, possibly by a human, but more likely by a machine. We are talking about the document that describes what the program is intended to do, which is then followed to carry out the tests.

> They are not for humans to read

I should hope your documentation is there for humans to read. If not, even small modifications required as business needs change would become a complete nightmare. The tests you need to perform, and thereby the documentation that needs to be followed, will not remain static through the entire lifetime of the application.

TDD = Test Driven Development

It's not comprehensive documentation, it's a process of software development. Start with the most simple test first, make it green via the most simple implementation, refactor. (Red/Green/Refactor). Repeat until you can not adjust your tests/specs and implementation anymore.

Doing TDD you'll not create comprehensive documentation upfront but will switch your testing- and implementation-hat every few minutes.

> It's not comprehensive documentation

Not at first, but by the time your software is working, you will have comprehensive documentation about it.

> Doing TDD you'll not create comprehensive documentation upfront

Where did the idea of 'upfront' come from? Having comprehensive documentation before you have working software doesn't mean having comprehensive documentation before you have any software.

Reply on news.ycombinator.com