a relief to read this and see that I'm not alone in my desperate frustration re: tensorflow '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"

Show thread

@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. ;)

@aparrish OpenStack is exactly like this, too. I worked with it for a summer job and the documentation just... Isn't constructive. It has solutions and theory, but nothing except an endless list of API options to connect them.


> They keep releasing new abstractions that are hard to port old code into, and their documentation advocates constantly porting everything to keep up

This is such a google thing to do. We used to joke that “there is no problem you can’t solve by adding another layer of abstraction”. This is what the dev experience inside google is like, too - the teams you depend on are CONSTANTLY coming to you insisting you drop your work to migrate to their new, wildly incompatible API.

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.