[HN Gopher] An engineer's tips for writing documentation devs love
___________________________________________________________________
An engineer's tips for writing documentation devs love
Author : kiyanwang
Score : 221 points
Date : 2022-07-01 13:09 UTC (1 days ago)
(HTM) web link (thenewstack.io)
(TXT) w3m dump (thenewstack.io)
| powersnail wrote:
| 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.
| hintymad wrote:
| > "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.
| bsder wrote:
| > 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_.
|
| So, no, I don't want to learn.
| xorcist wrote:
| 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.
| g9yuayon wrote:
| 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.
| dekhn wrote:
| 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
| remram wrote:
| Also: if you have to tell me it's simple, rather than showing
| me examples that make it apparent, I assume it's not.
| wwalexander wrote:
| 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.
| 411111111111111 wrote:
| None of the technologies you've named could be considered "
| _6-month-or-less half-life stuff._ "
|
| Puppet in particular is ancient by tech standards and is still
| getting used to date.
| hintymad wrote:
| 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.
| henrydark wrote:
| They're being used, but less for new projects
| [deleted]
| [deleted]
| WalterBright wrote:
| 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.
| AlchemistCamp wrote:
| Digital Ocean has, bar-none, my favorite dev docs on the
| internet.
| 8ytecoder wrote:
| Stripe is pretty good as well
| dotancohen wrote:
| 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).
| solardev wrote:
| Yeah, it's amazing how often I ended up at DigitalOcean to
| understand a competitor's architecture.
| Brystephor wrote:
| > 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.
| ag408 wrote:
| Super helpful Mason, thank you!
| kojeovo wrote:
| 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...
| Apocryphon wrote:
| 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.
| rojobuffalo wrote:
| > 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.
| onionisafruit wrote:
| 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.
| euroderf wrote:
| > 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.
| mmegger wrote:
| Hey look, I made it to Hacker News. Neat :) Glad y'all enjoyed
| the presentation and article
| brody_hamer wrote:
| I've definitely added 'digitalocean' to a search when I wasn't
| finding documentation I loved.
|
| "MySQL replication setup"? Nope.
|
| "MySQL replication setup digitalocean"? Ahh that's better.
| AtlasBarfed wrote:
| 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.
| solardev wrote:
| 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.
|
| I wish more devs/engineers wrote like that!
| edmundsauto wrote:
| 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.
| WalterBright wrote:
| > 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.
| spaetzleesser wrote:
| 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.
| dotancohen wrote:
| These tech writers should be following the steps and verifying
| the engineers' rough content, not merely translating it for the
| masses.
| ulisesrmzroche wrote:
| Nah, this article is poison. Downvote me all you want.
| hahnbee wrote:
| what makes you say that?
| nathias wrote:
| here is a simple trick to avoid writing bad documentation: don't
| delegate it to superseniors working on the project for a long
| time
| sdoering wrote:
| For those interested here is the original talk the article is
| referring to:
|
| https://youtu.be/9WobKoE9OPI
| 29athrowaway wrote:
| 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.
|
| 9. Conciseness.
| jacobyoder wrote:
| > 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).
| ilrwbwrkhv wrote:
| The memcached story
| https://github.com/memcached/memcached/wiki/TutorialCachingS...
| is still an iconic piece of dev writing for me.
___________________________________________________________________
(page generated 2022-07-02 23:00 UTC)