An engineer’s tips for writing documentation devs love
thenewstack.io
thenewstack.io
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.
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.
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.
Puppet in particular is ancient by tech standards and is still getting used to date.
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.
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.
Ansible is not bad but tf is Terrible. Good idea, terrible execution and evolution
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.
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.
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 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.
So, no, I don't want to learn.
Flutter and Dart are actually some of the more interesting things that I'm not so irritated learning.
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.
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.
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...
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.
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 ⁴).
¹) https://people.inf.ethz.ch/wirth/index.html
²) https://people.inf.ethz.ch/wirth/CompilerConstruction/index....
³) "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."
⁴) https://people.inf.ethz.ch/wirth/FPGA-relatedWork/index.html
(edit: And, of course, there's FPGA implementations of Professor Knuth's MMIX (http://mmix.cs.hm.edu/), too: https://github.com/tommythorn/fpgammix)
(FPGAs did not appear for another decade.)
Don't say your product is the best, the greatest, the simplest, the most powerful. That's marketing BS, noise.
It's ok to say things that can be verified, like it's the cheapest, the fastest, the only one with yellow spots.
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.
It is still a hermeneutic circle.
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.
I wish more devs/engineers wrote like that!
One of the reasons documentation sucks is because we expect people to write well without editors.
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.
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.
Now I write documentation for a living, and I still do the same. It's just a lot harder to tail my readers.
Ages ago, I transitioned from UI to tech writing. I usability tested all of our docs, pretty much as you describe.
Thereafter, my products received very few tech support calls.
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.
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.
9. Conciseness.
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).
Format code as code, text as text, math as math.
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.
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
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.
I don't expect my target demographic to be familiar with those terms.
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
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.
Tell them why they are here, so they know if they disagree.
The first paragraph of a page should be the confirmation that you are on the right page.
By that, I mean that it should explain what and why. "This page shows you how to request a new API key. You must request an API key to..."
Then there's the table of contents that guides you to the step you care about.
* Read it start to end without making edits. It interrupts the flow.
* Read it out loud.
* Pass it through Hemingway to find long or complex sentences.
* Write common questions on a sheet and see how long it takes to get the answer from your text.
“MySQL replication setup”? Nope.
“MySQL replication setup digitalocean”? Ahh that’s better.
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.
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.
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.
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.
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.
yes, build a better terraform. build a better puppet. building again and better is the only solution, always has been.
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.