Mastodawn

Rainhard Mar 25

Matthew Garrett

Trying to convince my students that having all your security policy changes include a design doc describing the status quo, the desired outcome, why this change will achieve it, why alternatives were rejected, and then implementing it via some automation schema so it can't accidentally be reverted for no obvious reason is good actually

Matthew Garrett Mar 20

They have apparently never known the pain of it being literally impossible to determine why something is the way it is and having no idea whether changing it will break anything

Lars Wirzenius Mar 20

@mjg59 Ah to be young again. Software development in general is much easier when you're young, with good memory, and working on something that didn't exist last week. It gets harder the older you get, the older the project gets, and the more people have been involved.

dr2chase Mar 20

@mjg59 if nobody could be arsed to document it, it must not be important.

Matthew Garrett Mar 20

@dr2chase that is a justifiable position and unfortunately if you then take down prod anyway it doesn't help your defense if you have nobody to point to

Aristotelis Tzafalias Mar 20

"Theory is when you know everything but nothing works. Practice is when everything works but no one knows why. In our lab, theory and practice are combined: nothing works and no one knows why."

Tobias Klausmann Mar 20

@mjg59 "Why yes, Mr. Chesterton, you *do* need a building permit for that fence."

andreaskem Mar 20

@mjg59 Where I work, we have legacy C and Pascal code, some of it from the early 90s. Barely any documentation or comments. No version control was used back then. Unit testing was unheard of. Changing anything in there is scary as hell. The prospect of seniors retiring causes some real worry.
This experience really drove home how important commit messages, tests, and comments are. Write that stuff down! Make people write that stuff down!
Also: Allowing people to keep this information only in their heads *will* lead to trouble. Imagine being too scared to fire somebody or even disciplining them because they might quit. There won't be any levers you can pull to keep them in line. And, at some point, they *will* no longer be there. You won't even be able to make them produce documentation before they leave.
Having to perform code archaeology and reverse engineering on your own codebase is not a good way to spend your time.

Lars Wirzenius Mar 20

@mjg59 Should there also be a description of how to verify the changed policy achieves the purpose of the change?

This is all well and good until you realize that "some automation schema" was implemented wrong, and/or had known issues, or discoverable ones, and that it brought everything else down with it.

Matthew Garrett Mar 20

@7heo sure, and then that's something you fix. Unlike "A human manually applies this policy" which, based on personal experience, is going to end up in some number of cases with either the wrong policy being applied or no policy being applied and there being no record that lets you work out why

Oh. Yeah. Point taken.

e. hashman 🇵🇸Mar 20

@mjg59 I can't understand why people hate design docs so much because they are the only way I get anything done

@mjg59 Next step: generalising this to all changes.
Seriously, this is a long way towards a good change-management system.

The only obvious things I'd add are a list of things that could be impacted, how you'd know whether they were affected, and a rollback plan.

Fazal Majid Mar 20

@mjg59
Chesterton’s Fence

Captain Observant Mar 21

@mjg59 Agile dev: Documentation is a waste of time; instead spend hours estimating work in imaginary units of effort. Agentic AI dev: there will be a 500:1 ratio of documentation to code, which nobody reads.

Development "best practices" change like Jean styles.