Notices by Ben Zanin (gnomon@mastodon.social), page 3

@mntmn that is adorable, those little cells are just doing their very best

@mntmn it's so, so good

I love that my experience with software is so rich with documentation: the output of -h/--help, man pages, GNU info pages¹, README files in repo roots, code comments, commit messages (especially those rare but wonderful annotated git tags which explain the why and how of features being merged!), printed books about tools that have been stable and useful long enough to earn that honour, specification docs, mailing list archives... it's so deep and rich, so satisfying to read.

¹: yes, yes, I know

And research papers! About the underlying algorithms, and about comparative surveys of tools with different implementations, and about social factors of groups of people who use different toolsets! Can't forget about those, absolutely love them.

I have a particularly warm and fuzzy feeling about programming languages that allow and encourage the use of function docstrings, especially when there is accompanying tooling to make structured use of them so they're more than just code comments with bonus opportunities for syntax errors. Hypertext codebase navigation, persistent variable customization, interactive calling conventions, all that jazz.

Oh and logging! And metrics! Also delightful!

I think what I most appreciate about all this documentation is the work that goes into making complex things more understandable. (Or at least the attempt. I'll let you know if I ever build up some level of comfort about neteing kubers, but I ain't there yet.)

The thing that makes all that possible and valuable is *time*. It requires a development cadence slow enough that writing can keep up with it. It requires prioritizing a cadence slow enough for readers to internalize & understand it.

Give me smaller, simpler, slower software, written by fewer people, under less pressure, intended for longer service. Please!

@mntmn BOO

@mntmn yay!

@mntmn https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/mmc/host/sdhci-esdhc-imx.c#n1462