Conversation

Notices

1. Ben Zanin (gnomon@mastodon.social)'s status on Friday, 20-Jan-2023 08:45:21 JST Ben Zanin

   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

   • Ben Zanin (gnomon@mastodon.social)'s status on Friday, 20-Jan-2023 08:45:17 JST Ben Zanin

     in reply to

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

   • Ben Zanin (gnomon@mastodon.social)'s status on Friday, 20-Jan-2023 08:45:18 JST Ben Zanin

     in reply to

     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.

     Adrian Cochrane repeated this.
   • Ben Zanin (gnomon@mastodon.social)'s status on Friday, 20-Jan-2023 08:45:19 JST Ben Zanin

     in reply to

     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!

   • Ben Zanin (gnomon@mastodon.social)'s status on Friday, 20-Jan-2023 08:45:20 JST Ben Zanin

     in reply to

     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.