Adam Dymitruk   

"Yes, but all #documentation is technical debt. You constantly have to update it. It’s always wrong. Consequently, you should write as a little of it as possible."

👆 The worst take that keeps fueling #agile zealots.

This keeps pushing the "#code is documentation" racket. No, documentation needs to be there because it's the only thing that destroys the silos. Because we had a bad way to document doesn't mean we don't fix the core problem of making documentation effective.

Nov 13, 2022 at 6:04pmWeb
Show threadAdam Dymitruk   Nov 13, 2022

The best documentation is a #design diagram that's used for communication to run the project - not something used by only one or 2 roles in the organization.

Roping this into #TechnicalDebt is just absurd. And tech debt is such a bad analogy anyway.

This dysfunction in the supposedly advancing computing trend of agile is what forced us to come up with #EventModeling

Show threadDirk-Jan SwagermanNov 13, 2022

@adymitruk on documentation; have you come across https://esi.nl/research/output/methods/a3-system-overview?

On technical debt, I started to call it software “inventory” https://www.linkedin.com/pulse/hidden-costs-software-inventory-dirk-jan-swagerman

What do you think about that?

A3 System Overview

ESI
Show threadAdam Dymitruk   Nov 13, 2022
@djswagerman too detailed, too technical.
Show threadDirk-Jan SwagermanNov 13, 2022

@adymitruk in an embedded systems context, the A3 already reduced existing architecture docs significantly. Not sure if you can reduce much further without negativity onboarding or new employees.

What do you use?

Show threadAdam Dymitruk   Nov 13, 2022
@djswagerman #EventModeling
Show threadezaquariiNov 13, 2022

@adymitruk Some cultures just don't care, and often for good reasons. Startups that are done after 1y, agencies that make one-off apps, etc, etc.

Roping into #TechnicalDebt is just rationalization of their position.

However, authoritatively pushing this as general advice that suits all is a sign of ignorance, if not arrogance.

Show threadMark Rogaski  🏳️‍🌈🦓Nov 13, 2022
@adymitruk I agree. But even if you accept that, diagramming communication in a event-driven architecture is very difficult. UML isn't sufficient, BPMN is too complex, and C4 only prescribes granularity. What do you find to be the best way diagram "this is how it should work"?
Show threadAdam Dymitruk   Nov 13, 2022
@mrogaski #EventModeling focuses on state changes which is the sweet spot.
Show threadChris SimpsonNov 13, 2022

@adymitruk
✅ Documentation is great, you're just doing it wrong
❌ Agile is great, you're just doing it wrong

(Apologies ♥️)

Show threadAdam Dymitruk   Nov 13, 2022
@chris_e_simpson except we had 100% focus on agile and 0% on design/documentation
Show threadChris SimpsonNov 13, 2022
@adymitruk it was a cheap shot and flawed at best
Show threadAdam Dymitruk   Nov 13, 2022
@chris_e_simpson I appreciate it coming from you ❤️
Show threadJess AndersonNov 13, 2022
@adymitruk so often skipped, and it slows everybody down. We’re still human and tend to be afraid we’re the only ones with a dumb question, so just go along. Design diagram gets everyone in the same page and gives the ability to ask questions in context.
Show threadPhilNov 13, 2022
@adymitruk I use flowcharts and short explainers frequently. My only long documents are the ones the certification body says I have to carry. My org only reads them in prep for the annual re-cert 😉
Show threadDale EmeryNov 13, 2022
@adymitruk Say more about how documentation destroys the silos.
Show threadAdam Dymitruk   Nov 13, 2022
@dhemery is usable by multiple roles opening the communication channel to be real-time instead of passing off artifacts over a wall to a different role.
Show threadDale EmeryNov 13, 2022
@adymitruk Do you mean because the documentation is published as a separate artifact, separate from the code, and accessible to people who don’t have or need the code?
Show threadAdam Dymitruk   Nov 13, 2022
@dhemery yes, but it's close enough to implementation yet not drowning in detail to make it guide and document the code.
Show threadnoivadNov 13, 2022
@adymitruk: documenting your work (not just programming) allows you to put reminders in it for your later use. That way when you come back to it 6 months (maybe a few years) later to improve something, you know what the hell you were thinking when you wrote it. A few concise notes in comments has saved my bacon more than once.
Show threadAdam Dymitruk   Nov 13, 2022
@noivad yes, and the ultimate format for that is #EventModeling. I can come back to a project years later and pick up on a new feature in MINUTES, from any perspective including coding.
Show threadnoivadNov 13, 2022
@adymitruk I did something similar to Event Modeling years ago (when I was still writing stuff in PHP, but I called it a workflow.
Show threadAdam Dymitruk   Nov 13, 2022
@noivad there definitely had been thousands of different notations and diagrams. What made this work was focusing on events as the building block of state. It's extending the #EventSourcing mindset to all systems automation and even manual pen and paper systems.
Show threadezaquariiNov 13, 2022

@adymitruk Writing documentation is a great tool to discover bad design. So often "can't document it" runs alongside "spaghetti design". It is astonishing how many #bugs we discover just by writing #documentation and realizing that something simply doesn't make sense.

And it's not only end user documentation, but code and test scenarios (#bdd) as well.

Show threadRod LecocqNov 13, 2022
@ezaquarii @adymitruk
Totally agree with that. I can't count the number of times I corrected / changed my design after documenting it and realizing it didn't make sense (even if everything worked, tests passed and everything was fine... well for now, probably not after a few, feature requests)
Show threadGhostGrrlSpyNov 14, 2022
@ezaquarii @adymitruk As a career tech writer (both end-user & developer facing) I can’t tell you the number of issues I’ve helped developers identify before they became major issues. Information developers are the first line of testing and make a point of doing things “wrong/illogically” because we know, somewhere, a user will. Writing clear, concise, useable, engaging, documentation is an art, just like coding is, that deserves more attention and appreciation. It isn’t easy.
Show threadAdam Dymitruk   Nov 14, 2022
@GhostGrrl007 @ezaquarii hopefully #EventModeling makes it easier
Show threadMaankoeNov 13, 2022
@adymitruk I've had success with https://structurizr.com before, nice tool
Structurizr

Visualise, document and explore your software architecture with Structurizr

Show threadAdam Dymitruk   Nov 13, 2022
@maankoe this is more about workflow design
Show threadMaankoeNov 13, 2022
@adymitruk ok, I'm just making a comment on some useful documentation I've managed to get a team on board with. It's not mutually exclusive.
Show threadSidNov 13, 2022

@adymitruk IMO, addressing it as "Agile zealots" is a bit reductive. A *lot* of people who profess to follow Agile only give it lip-service, and ignore the actual principles and rationale that drives it, which defeats the purpose. I've heard it termed as Fragile Development from time to time.

1/n

Show threadSidNov 13, 2022
@adymitruk From what I've seen, the main driver for documentation is that code tells you WHAT happens and HOW it functions, but it'll almost never tell you WHY. And when the code's incorrect (a bug, or a change in business direction), not knowing why something was written will make it ridiculously hard to change safely or easily. Documentation captures intent. I've been meaning to write a full post on this; there's a lot to unpack there (feeble mind likes to procrastinate).
2/n
Show threadSidNov 13, 2022
@adymitruk I'm interested in the idea of #EventModeling though, it's not something I'm personally familiar with so I'll need to look it up. Interested to see how it deals with these problems. Thanks!
3/end
Show threadAdam Dymitruk   Nov 13, 2022
@sid I have lots of material including meetup recordings and podcast interviews.
Show threadAdam Dymitruk   Nov 13, 2022
@sid I would agree 10 years ago. It's now accepted as "the proper way to run projects". So people that want to entrench you more into what's acceptable and cover up core issues instead of trying to find better ways get that label.
Show thread𝚃𝚘𝚖 𝙷𝚘𝚠𝚊𝚛𝚍Nov 13, 2022

@adymitruk I'm probably one of those #agile zealots 🙋‍♂️, but no, I don’t think of documentation as technical debt.

I think documentation for the sake of documentation is waste (#lean zealot?), but good, well written documentation is worth it’s weight in gold.

#ReadTheCode and #ReadTheTests is cruel and unusual punishment for most codebases I’ve had to learn about.

Show threadAdam Dymitruk   Nov 13, 2022
@tomh and it's inaccessible to non-programmers - and even programmers that work in a different programming language.
Show threadRod LecocqNov 13, 2022
@adymitruk
1/2
I would add that this "no documentation" habit has an other very pervert effect, especially on young developers who never worked in the Pré "Agile everywhere" era :
they are so used to not document, that they don't expect or don't even think that a piece of software they are using could have a good documentation.
How many times I ask : "why did you do that complex thing when your framework could do it for you very easily ?"
Show threadCindy PotvinNov 14, 2022
@adymitruk So true! I've never regretted writing documentation; it's not always immediately useful but it's great to wonder why something was done 10 year ago and be able to find the answer. Pretty rare to see this with agile projects.
Show threadAdam Dymitruk   Nov 14, 2022
@cindyptn you may find #EventModeling helpful to get others to participate with you.
Show threadDavid RawheiserNov 15, 2022
@adymitruk I like to think documentation as retrospective design documents. Not what is was supposed to be, but what it really is.