a relief to read this and see that I'm not alone in my desperate frustration re: tensorflow nostalgebraist.tumblr.com/post 'a certain category of currently popular software... [has] a bundle of frustrating qualities like: [...] Documentation is a chilly API reference plus a disorganized, decontextualized collection of demos/tutorials for specific features written in an excited “it’s so easy!” tone, lacking the conventional “User’s Manual” level that strings the features together into mature workflows'


also: "Built to do really fancy cutting-edge stuff and also to make common workflows look very easy, but without a middle ground, so either you are doing something very ordinary and your code is 2 lines that magically work, or you’re lost in cryptic error messages coming from mysterious middleware objects that, you learn 5 hours later, exist so the code can run on a steam-powered deep-sea quantum computer cluster or something"

@aparrish i have literally no idea what tensorflow is and yet already don't like it

@aparrish anyway not a fan of complex software with useless documentation

hey, remember PostgreSQL? where a feature will not be merged until it's adequately documented, no matter how cool and important and in demand it is

@hirojin all things being equal I would 1000% prefer any framework or service that makes this promise. (or even better: "we will not merge any new features ever")

@aparrish ime, if you commit to good documentation, you can't not commit to good design

this then makes every new feature an act of careful deliberation

@aparrish this is the hinge! the fulcrum of software!

it kind of hurts that each software, each library, has to re-define it's own construction kit, build it's own world-space to exist inside of.

imo we're missing user-accessible general spaces, that libraries could then enrich & extend user's capabilities in.

the stack is too damn high & not near modular nor extensible enough.

docs taking the time to show how to construct the pieces would definitely be a valuable win, while others work on overhauling the general software systems paradigms. ;)

Sign in to participate in the conversation
Friend Camp

Hometown is adapted from Mastodon, a decentralized social network with no ads, no corporate surveillance, and ethical design.