[nonethewiser]

Probably an unpopular opinion, but if you want rock solid documentation, switch to waterfall.

I just dont think its possible with agile. It's always lacking. There are degrees of quality, sure. Aspire for good documentation. But there are too many moving parts by too many hands and there are diminishing returns on documentation efforts.

Also consider that every piece of documentation you write adds onto the documentation burden. The more you document, or the more specificity you give in documentation, the harder it is to have accurate docs. Auto-generating stuff gets around this but is usually of limited value.

[tremon]

Of course it is possible with agile, it "just" needs to be properly prioritized. And that also means, in good Agile fashion, that documentation skills needs to be represented in the team. If you don't prioritize documentation and do not value technical writing skills, it doesn't matter whether if you use waterfall or agile processes, you will still end up with sub-par documentation.

Also, what kind of documentation? High-level design documentation? Low-level code documentation? Code structure reading guides? End-user manuals? Elevator-style sales flyers?

[j45]

Documentation in some ways is more of an important output than code.

Documentation serves to to create beginners with the source code and project.

When working with devs it’s made clear that what they are delivering is documentation of which working code is one part.

The ability to write sentences in documentation is as important as writing code.

Writing as one works (not after) and then editing is one of the only ways I’ve found that there is a chance, waterfall, agile or cowboy.

[a4isms]

As an exercise, change your statement from ”If you want rock solid documentation, switch to waterfall” to,” ”If you want rock solid tests, switch to waterfall.”

They have all the same organizational forces acting upon them. You don’t need all the tests to “ship a feature.” So some people can certainly skip some or all of them.

Switching to a highly iterative process neither worsens nor improves the quality/completeness of your test suite. Rapid evolution of features places pressure on keeping test suites current.

Iterative processes with good tests in place exist only because entire engineering departments have “gotten religion” about their value, and product managers have come to accept that it’s important to invest in tests. If they didn’t, they’d give engineers too much work in too little time to write tests.

And so on and so forth. Great tests and entire infrastructures around tests only happen when an entire organization buys into their value even if everyone knows you can get away with writing a negligible amount of test coverage and still ship a feature.

I submit it’s the same thing with documentation. It’s not a process problem, it’s an “embracing their value” problem. If you’re in a culture where tech writers are not considered as valuable as engineers, you will have crappy documentation no matter what you do to the process.

[crazygringo]

> I just dont think its possible with agile. It's always lacking.

I don't think it has anything to do with waterfall vs. agile. If, in agile, you declare that no story is ever complete until the documentation is complete (same as it's not complete until it passes testing), then boom, it works.

Documentation has nothing to do with methodology. All it has to do with is whether the manager/lead signing off on completion requires documentation to be considered part of that, and enforces that.

It's nothing about "degrees of quality" or "aspiring". Either it's enforced policy or it isn't.

[simonw]

Keep your docs in the same repository as your code and enforce relevant documentation updates as part of the code review progress. Works great.

[trynewideas]

I've held that view before, but in practice adding friction to review and deployment doesn't accomplish much other than frustrating engineers.

Aside from that, the code review process is also too late. A better spot would be during the design process, then updated alongside the implementation to match. By the time you get to code review, the docs for the relevant code should naturally already be written, without needing to set and enforce a docs requirement.