> "You'd be surprised how many people get turned off by seeing something that other people tell them is simple, and then it's not simple to them."
This. This should be every platform/infrastructure engineer's motto. Don't tell me your DSL is simple. Don't tell me that Puppet is so simple because oh my god, it uses Ruby. Don't tell me that HCL or terraform or whatever yaml crap is so simple because "they are in yaml". No. They are not.
Don't. Make. Me. Learn. It's not because I don't want to learn. It's because I want to learn fundamentals instead of your specific, non-generalizable, 6-month-or-less half-life stuff.
My sophomore calculus Prof, whenever he'd introduce a new concept he'd say "ees treeveeal!" It was a such a trademark that the students would keep a log in their notes of every "ees treeveeal!". (Of course, the joke was none of it was trivial.)
One day, he remarked that this new concept "ees non-treeveeal". We knew we were in for it then!
My jet engine Prof would lay out the boundary conditions of a problem. Then, "Und now zat vee haff zee eekvayshuns, vee merely turn zee krank!"
What can I say. I enjoyed those classes very much.
This gives me flashbacks to undergrad engineering courses. Nearly none of my professors, at a top 10 electrical engineering program, were able to explain things very well. Then you'd have to dive into poorly written textbooks to figure out what was going on. Kids these days have no idea how good things are with lots of youtube videos and online tutorials that give clear explanations for how things work. Even then, I noticed my old engineering program is still managing to fuck things up by doing things like using synthetic, poorly documented fictional microprocessors to teach assembly and computer architecture.
[I'm well aware of who I am replying to here, I'm merely taking the bait and providing some hopefully fun links for people to dig into. :)]
Because that's how Professor Wirth ¹) does it ²), because it allows for some interesting educational side-treks ³), and because the difference between a fictional and real microprocessor is smaller than some might think ⁴).
³) "So what instruction would you add to this CPU to make the work we've been doing easier? Great, implement that instruction in the provided emulator."
Yeah, well, I learned on a real 8 bit microprocessor (6800). It has about 40 instructions, all are simple. It's quite a dopamine hit to run your first program on an embedded system and see it working. It felt like being Master of the Universe!
I had a freshman year calc professor who also loved to label lots of concepts as “trivial.” It became a meme in my friend group. Unfortunately for my GPA, it was extremely nontrivial for me — I was only saved by a (nontrivial) amount of eleventh hour effort to absolutely smash the final.
> Don't. Make. Me. Learn. It's not because I don't want to learn.
I disagree. I. Don't. Want. To. Learn.
Almost nothing in between me and getting my problem solved is interesting nowadays. Everything I have to learn is just another yak I have to shave in between me and getting my problem solved. This is doubly irritating when the yak is infrastructure (configuration systems, build systems, source control systems, etc.) that has zero bearing on my problem.
Here was one: "We want to add audio to our phone app." GROAN.
App is in Flutter on Android which implies:
1) Flutter
2) Dart
3) Gradle (dear God, help me)
4) Groovy
5) Oboe (for sound on Android) implying
6) Android NDK
7) CMake (hey Satan, I'll take your help too)
8) C++
And I'm leaving out a bunch of stuff. And there will be even more for iOS.
NONE if this is interesting to me. Only 2,5 and 8 are directly applicable to my problem. Everything else is a tower of garbage that I have to chop through with a machete in order to get to the task that I actually want to solve.
And, as I understand it, somehow the web and Javascript universe is worse.
Good example. "Another yak to shave" is a great analogy too. I think we are saying the same thing: we don't want to learn anything that has no direct bearing on our problems. Learning how to design an infinitely scalable metadata service for a stateful service is a delight. Learning how to use Terraform is an abomination.
This is a classic issue of leaky abstractions, so it is definitely "caused" by Flutter/Dart. What led to this might not be their "fault", but as it stands this is something that only Flutter/Dart can solve.
It is not strictly necessary to use Gradle/Groovy to build an Android app, so to use it was Flutter/Dart's choice. Just as it isn't necessary to use Xcode, Cocoapods or Ruby (of course, you still need either Objective-C or Swift, but only one) to make an iOS one. Same for Oboe: it could be prebuilt rather than leaving it all to you (although depending on how you're using it, it's debatable if it's Flutter/Dart's concern).
The bottom part of the stack doesn't have control over the top part. Gradle can't really modify itself so that Flutter's abstraction is no longer leaky. Save for some ruling by Google/Apple/etc, the reason you need the whole stack is not because of some fundamental need, but rather because it was a choice made by the tools at the top of it.
> It is not strictly necessary to use Gradle/Groovy to build an Android app, so to use it was Flutter/Dart's choice. Just as it isn't necessary to use Xcode, Cocoapods or Ruby (of course, you still need either Objective-C or Swift, but only one) to make an iOS one.
This may all be technically and pedantically true, but I have never seen an app built without either of those stacks. And I've been doing this an awful long time.
Yeah, because of a technical choice made by higher level tools.
And I've worked on a few games that didn't need some of those. On iOS's side there's Swift Build Sysyem and Swift Package Manager that almost remove the need for Xcode. And there's also things like Cordova where some of those things are used but fiddling with them isn't needed for 99% of the cases.
It's funny how this is similar in the frontend where people constantly complain about the tooling, but as soon as they hear that apps can be built without bundlers/transpilers (because modern browsers support A LOT of things), but go "yeahhhhhh right but in practice you need webpack because I never seen anything without it in my super vast experience of building the same thing over and over and over". Well...
While I understand the sentiment, I don't really get the particulars.
So, instead of learning Puppet or Terraform, you want to implement one from scratch?
I have that itch too, I also try to implement the basics of something like git or Ansible in my own toy system when learning it. But that's just to get some hang of why the tool looks like it does. I'm still there to use the tool.
That goes double if you're working with others. I totally get the bit about wanting to learn fundamentals, but not the bit how it turns you off some higher level tool.
Not really. Use whatever technology that you know best, but hide unnecessary complexity through the right tools. I'm not sure about the OP, but I had extremely good experience when I was in Netflix. A single engineer, Joe Sondow, created the app Asgard. Using Asgard, I didn't need anyone to teach me how to configure clusters or networking topologies. The app got affordance, consistency, and constraints right, to the point that at any point what I guessed was either right or the only way to complete my tasks. Michael from the cloud team created command-line tools for managing AMIs. They exposed just what one needs to achieve while hiding anything about how things were done. As a result, I can still remember how to use these tools, years after I left Netflix. Similarly for doing service discovery, fault injection, load balancing, autoscaling, predictive autoscaling, logging events, publishing metrics, and the list can go on. Everything in Netflix, at least when I was there, followed the unspoken principle of making everything a non-event: zero unnecessary mental load, maximum flexibility, maximum freedom to engineers, and full transparency. Things just happened. Tools were just in place. The tools could be primitive and could lack of features, but the they did not get in my way whatsoever.
> [The AMI management tools] exposed just what one needs to achieve while hiding anything about how things were done
No, they exposed just what _someone working at Netflix who produces AMIs for Netflix's infrastructure and is required to conform to assorted Netflix expectations lest they be told to go pound sand_ needs. Accepting that constraint makes the problem much easier. When you try to make a general-purpose tool, you rapidly run up against:
- Some other user needs to do something that you don't, that the existing configuration surface cannot possibly account for. You now have either a tool that exposes two (and soon, three or four or five ad infinitum) means of doing thing (likely without any indication why you'd use one or the other) or a tool that exposes <original means of doing thing> and <fill in your own thing from scratch>.
- Someone has other parts of their infrastructure whose design is, for lack of a better description, "fucking stupid". They don't have the power or will to change that, but they're happy to ask you to include a workaround for it in your product. They also have a number of friends whose surrounding infrastructure is similarly fucking stupid, and some of those are important contracts where sales will force your hand to build the workaround instead of asking the customer not do fucking stupid things.
Yes, a single well-managed organization can delegate various pieces of complexity throughout the org and avoid having other parts worry about them. General-purpose tools do not have that complexity. The reason you have to learn new concepts and tools to learn Terraform effectively is because you're taking all the complexity of dealing with a cloud services provider and then adding an additional layer of complexity on top to augment the things you can do with the cloud provider. The value proposition is that this still better than what you'd do by hand and, crucially, something that other people who know Terraform can understand. Realistically, you can hire another engineer who's familiar with Terraform. You can't clone Matt.
> So, instead of learning Puppet or Terraform, you want to implement one from scratch?
I definitely don't want to implement from scratch.
I share his sentiments. I keep hearing about Puppet Labs (i think is the right one), but I've been to the site a bunch of times and I end up leaving because I have no idea where to start. So I really donno how I would benefit over just using a few bash scripts or powershell scripts to manage my Linux/Windows servers inn AWS.
Many different things are like this. The barrier to entry is high, once you get started it becomes easier and you tend to agree that the tool is much better than other alternatives.
However I today learned that Pinia is the state management library that replaces Vuex in Vue. (effectively V5 of Vuex) and I opened up the documentation, and within a few minutes of reading I had it up in running in my little side project. The documentation explained why its now Pinia, and gave a concrete working example of a simple counter and how its used.
Vue, Rust, Postgres - these all have my favourite documentation.
If a few bash scripts is enough for you to manage your servers, you probably don't need puppet (or ansible, or chef).
But, yes, I agree that the puppet documentation is (or at least was, I have not looked at it for several years) not entirely brilliant. It is an OK reference manual, but like so much documentation, it is more difficult than necessary for learning the thing.
I don't understand how you were able to make the jump to "I don't like tools that lie about complexity" to "I want to build tools from scratch", but I share GP's complaints. The problem is clearly with tools that promise simplicity for users but are actually only simple for the creators of the tools themselves. For end users there's still a lot of complexity.
And it's not that complexity is a problem per se. It's just that it exists on multiple levels. And some of those tools aren't abstracting much or anything at those levels. They're often just providing yet another thin API for something that's still complex for their users, so they haven't really made the hard thing simple, maybe they simplified the 10% of it that don't matter at the user's scale. If anything they introduced even more complexity. Aka, leaky abstractions. Of course, YMMV.
I wrote my own Ansible+terraform alternative and frankly, for the limited use (demo of GCE launch, we could start over 1000 raw vms and be doing large scale compute in minutes during the live demo (unfortunately urs wasn't confident so we pretaped that part).
Ansible is not bad but tf is Terrible. Good idea, terrible execution and evolution
I think it’s fair for a project as a whole to describe itself as “simple” as a statement of its goals (vs. e.g. “flexible”, “high-performance”, “easy-to-use”, and so on).
For example, Suckless Software describes many of their Linux applications as simple, and it’s a fitting description that also encodes the spartan nature of the projects compared to their more commonly used counterparts.
But outside of a README or GitHub project description, I completely agree. Simplicity is the absence of complexity, and will become in retrospect when users choose what you’ve made because you made it simple enough to do so.
I don't think it's fair. Simple is subjective. Goals should be objective. I don't want to know and understand the entire context in which a project was conceived.
Simple is subjective, which means it shouldn’t be used in contexts where accuracy and objectivity are paramount (like technical documentation).
But if I’m searching for e.g. a “simple monitor hardware brightness control for Mac” without extra nice-to-have features or GUIs, a project that describes itself as “simple” gives me a useful clue that the developers might have priorities that match my needs.
True. The shelf-life refers to how long one cares to remember the technology. The unfortunate fact is that these techs are so specific that I simply forget them weeks after I don't have to use them any more. The entire Uber engineering team had to endure the horror of writing hundreds of lines of oh-my-god-it's-so-cool-dsl Puppet for simple deployment tasks and waiting for on average 15 minutes before a change took place. Guess how many people missed Puppet when it was ripped off Uber's infra? Probably only the dude who thought Puppet and Graphite were the best systems in the world. And guess how learning the intricacies of Puppet helped anyone's career or ability to build better systems down the road? The answer is zero and zero.
I can relate. The thing is, that these "Heureka" moments stem usually from long times of frustration working within a certain domain or with a certain concept.
After working with certain stuff for long periods I can find usually a way to explain it in a very easy way. However, this does not mean, that concepts are easy to grasp without putting in more time and learning all about what my abstraction kept out.
This is such a pet peeve of mine, especially when peeking at other programming domains I don't typically work in. Seeing readme's say "Simply..." or just throw around domain terminology with 0 context immediately puts me off using the library.
I love this idea (for digitalocean) of "documentation as marketing". Every time I read one of their articles, I feel like "oh wow their engineers must really know what they're doing, to be able to explain this so clearly". I didn't know they had a team of professional editors... kudos!
Another team that's really great at producing documentation is the Cloudflare retrospectives/postmortems folks, who can very clearly explain the cascading failures from complex systems.
Editors are the key for any good writing. I've learned to assume that all good writing has a good editor/editing process, even if it's the author switching modes from creating to editing. David Sedaris writes amazingly well, and he says his "secret" is that every sentence has been edited and rewritten 19-20 times before it makes it into a book.
One of the reasons documentation sucks is because we expect people to write well without editors.
> David Sedaris writes amazingly well, and he says his "secret" is that every sentence has been edited and rewritten 19-20 times before it makes it into a book.
I used to know some US ballroom dance champions. You'd think they'd spend their training time going over ephemera. Nope. It was all about taking a step. They never stopped going over how to take a step. It's the foundation for all dance.
I love the ignorant phrase "they make it look effortless". Well, it is effortless when you've done it 10,000 times.
Insanely effective tip: watch a junior dev use your docs, offer no assistance, and have them say out loud what they're thinking and doing. You'll discover dozens of ambiguities, 'gotchas', and shortcomings!
It's important to use a new junior each time (i.e. if they've used your docs before, don't use that person again). They should also try to accomplish a real task (not just proofreading the docs, but actually using the docs for their intended purpose).
I've used docs from Salesforce and Google and can tell they haven't been tested in this way since they contain (glaring) problems that would easily be found and addressed in a few minutes.
I use this approach often, and gain enormously from it.
Having used a handful of dev nodejs Google docs in the past few weeks, at this point I can only assume that aggressively hate the devs trying to consume their stuff. Their docs (and examples, and TS types) are often out of date, missing details (eg missing docs on accepted parameters or even whole functions), and just require more codebase reading across multiple libraries to deduce usage.
This is how I wrote our company documentation. I'd watch new employees struggle and use that to improve things. My first pull request at a company was usually a README update.
Now I write documentation for a living, and I still do the same. It's just a lot harder to tail my readers.
I hate the trend of documenting by giving only examples and tutorials.
Examples are nice to get started, but completely useless otherwise. Please just give me a list of possible parameters/properties with their meaning, type and possible values.
For example, the Kubernetes documentation is a nightmare to me because it's not a real documentation, just a bunch of examples. Not only it is very inefficient to look for a very specific piece of information in that, but if my case happens not to be in it (which is most of the time) I can waste hours looking everywhere to finally learn that there is actually a x.y[0].z key that does exactly what I need.
Other example: Github actions. If you look hard enough, you may find something close to a yaml specification, but it's quite hidden, confusing and difficult to understand which property belongs to what. In contrast, CircleCI is extremely easy.
Worse is when the examples throw out some of the parameters or returned variables! Like a Python function that returns a tuple should never have an underscore in documentation.
1. Linear reading: define things before talking about them.
2. Make documentation explicit, not implicit: no acronyms or assuming context.
3. No marketing or self-promotion: your code is not fast, efficient, reliable, convenient or secure because you say so.
4. No ego: nobody has time to read about you or a story from your life. Keep that to your blog.
5. No humor: if it's 3 AM and you are debugging a problem, and you are being forced to read lame jokes to understand what some code does, you are going to get frustrated as hell.
6. Punctuation, grammar, orthography.
7. No aggression: Nobody has time to read rants as they're trying to work on code.
8. Prefer simple English, leave local idioms and slang aside.
> your code is not fast, efficient, reliable, convenient or secure because you say so.
I often would be in meetings where tech folks would introduce their code (to non-technical audiences sometimes) as 'tight' or 'super fast' or... similar. It was cringey every time, and... often wrong. Yay - you got a query down from 8 seconds to 2 seconds. That's not really 'super fast' though - with a bit more work (or experience) that would be 300ms or less (which I eventually did with about 30 more min of rewrite and indexes).
> Egger advises also writing out the full name the first time an acronym is used. Egger even links acronyms to their definition at the beginning or end of the document.
When someone does not do this, it irritates me to no end. It's so simple to do and is a major improvement. It goes from being a doc that is incomprehensible without understanding unexplained to a doc that beginners can begin to learn from.
Wait people use unintroduced initialisms and acronyms in technical writing? This is something that should always be avoided because it makes the barrier to understanding so much higher.
Internally we stress to avoid acronym abuse because it's that much harder to onboard. One of my colleagues from Austria compiled a spreadsheet of acronyms he's come across in our IT realm and it's at about 1300+ rows at this point. It's absolutely wild how much information is obfuscated by stuff like this especially when companies reuse the same acronyms to mean different things. A non-trivial amount of pre-sales failures (e.g. misleading clients on capabilities) came from use.of acronyms from one company which is also used by our company. The sales rep asking if we support XYZ and we go "yes" thinking they mean our XYZ but in fact it's some other XYZ that we don't support.
It's a horrible practice in our industry with no purpose. If it's too long to write, just set up autohotkey to expand these shorthands
Yep. I agree. Acronyms are just a bit more cognitive load when reading a doc. Using an acronym when you're talking to someone in your direct team or who works directly with you, that's fine imo. If you and I are working on service Aaaaaa Bbbbbbb Cccccc then it's fine for us to both call it ABC since it's been directly referenced.
But when reading a doc, you need to know who the audience is and what the purpose of the doc is. I can't think of an audience or purpose though where using acronyms without being fully written out on the first use is beneficial. Using an acronym without stating what that acroynm is is just gibberish.
It's because of this very problem which prompted the development of an auto-acronym-linker plugin in the browser (at the company i worked at)! This actually works pretty well.
I wonder why the tips mentioned in your talk are not applied to the article. As you said, engineers looking to improve their writing skills don't want to read a novel.
What are some of your favorite examples of existing documentation?
Libraries, platforms, etc?
Personally I've always thought Vue's guide to be stellar, and I use it as my North Star when writing my own docs. I also like Spring's tutorials but they're a bit messy
Another point I want to add is, try to read your own writing from the perspective of a reader. Readers are not yet familiar with the technology. They don't have a mental model like you do. Don't throw minute technical details or really abstract concept at your reader.
Somebody once described to me his note taking system as a networks of pipelines of data input and data output. I'm sure it means something in his mind, but it tells me nothing about his note taking system.
I highly recommend The Sense of Style by Steven Pinker. It goes into detail on how paragraphs and sentences are perceived by readers.
Not only this, but don’t assume your reader even knows they’re on the right page. Everyone has a different way of breaking down problems, and can click on the wrong link. They need to quickly know whether to hit the back button, before they’ve dumped all short term memory.
Tell them why they are here, so they know if they disagree.
Extracting the criteria about how to write good documentation out of this article is ... wait, this article about good documentation is itself bad documentation. Is that real irony?
Listicles are pilloried, but for things like this they are good practice.
I'm really disappointed in most documentation recommendations. I'll have to check out DO's docs. It would be nice to have a comparison criteria to help show what different techniques and structures work well.
Unaddressed is one of the greatest long-term issues, I have to deal with it all the time in cassandra and other fast-evolving platforms: versioning documentation for the specific platform, and SEO'ing it so newer documentation subsumes older docs in the search indices.
> The only thing worse than no documentation is incorrect documentation," he said. "Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time."
Basically: yes. Some here on HN will disagree, but they are IMO wrong. Another big time-waster for users is failing to write a document intro that identifies the target audience and the document's target information goals; it sucks to get 30 pages into the document before you finally manage to figure out that it's not the document you want/need.
Stripe docs are useful to devs utilizing or integrating with Stripe. Digital Ocean docs are far less focused on DO-specific technologies, I often browse their documentation even though I am using a competitor's cloud (AWS).
A lot of businesses would be well advised to hire tech writers who help with organizing, formatting and grammar. Engineers should provide the rough content. From my experience that's done pretty quickly but polishing the content and putting it into a document management system take a lot of time and expertise that engineers who also have development work deadlines don't have.
> the only thing worse than no documentation is incorrect documentation. verify instructions work.
i absolutely agree with the principle but i notice especially with internal projects that it is often not lived up to. once-valid docs become invalid over time. once you have the experience of getting bad information from a documentation project it loses credibility. readers ends up with extra work determining validity and communicating when changes are needed.
what does it look like when that problem is solved? i think of StackOverflow and DigitalOcean. they both have comment sections and date stamps. authors respond to comments. that's often how i figure out if something is still valid or not. it seems important that authors revisit or re-verify things they wrote. and if that's not something that is rewarded then it's not likely to happen.
This worry causes me to write less documentation than I probably should. I tend to see every line of documentation as a liability because I need to track whether future changes changes will make the doc out of date.
I would love some kind of dependency chart that goes from code to documentation where I can easily see what docs may need to be updated when I change a function.
I totally agree with foo and bar. These words literally mean nothing. I cannot fathom a situation where introducing arbitrarily named variables adds something meaningful.
Also funny how the article itself doesn't implement the tips it gives. No table of contents, no highlights, etc. I honestly expected a list of the mentioned tips at the beginning of the article.
Thought it was kind of funny that the article mentioned "Writers should value their readers’ time — and always try to get to the point." yet failed to do so. I missed the tips skimming through. Hit me with a TL;DR at the top...
Not impressed by this article either, but it's more of a summary of a presentation than a proper documentation. Though yes, it does suffer from a meandering dialogue-driven faux-journalist style and could really use bullet points at the top. This piece contains good info but the style smacks of content writing.
i’ve been trying really hard to write good docs lately[1]. it’s kind of terrifying to describe something as easy and fun knowing that it could be hard and rage inducing, but we have to try!
yes, build a better terraform. build a better puppet. building again and better is the only solution, always has been.
Back when I got involved in NancyFX, I started by just contributing to the documentation to make it easier to understand, filled in the missing pieces that I had to learn or annoy people by asking questions.
The only downside was after a couple of years, in the chatroom people would ask a question that 95% of the time resulted in just linking them to the docs and they said thanks it solved the issue. The other 5% was either not supported or resulted in improved docs.
This. This should be every platform/infrastructure engineer's motto. Don't tell me your DSL is simple. Don't tell me that Puppet is so simple because oh my god, it uses Ruby. Don't tell me that HCL or terraform or whatever yaml crap is so simple because "they are in yaml". No. They are not.
Don't. Make. Me. Learn. It's not because I don't want to learn. It's because I want to learn fundamentals instead of your specific, non-generalizable, 6-month-or-less half-life stuff.