8 ms·
An engineer’s tips for writing documentation devs love
- AlchemistCamp 4y agoDigital Ocean has, bar-none, my favorite dev docs on the internet.
- 8ytecoder 4y agoStripe is pretty good as well
- dotancohen 4y agoStripe 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 4y agoYeah, it's amazing how often I ended up at DigitalOcean to understand a competitor's architecture.
- spaetzleesser 4y agoA 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 4y agoThese tech writers should be following the steps and verifying the engineers' rough content, not merely translating it for the masses.
- brody_hamer 4y agoI’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.
- dzhiurgis 4y agoThose are tutorials :) which are useless without api doc/spec and visa versa.
- solardev 4y agoI 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 4y agoEditors 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 4y ago> 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.
- SOLAR_FIELDS 4y agoMason, the guy the article is about, has some really good videos on DO. I learned a lot about several terraform best practices by watching him spin up a production cluster: https://www.digitalocean.com/community/tech_talks/building-a-minimal-production-ready-infrastructure-on-digitalocean https://www.digitalocean.com/community/tech_talks/building-a...
- deleted 4y ago[deleted]
- nathias 4y agohere is a simple trick to avoid writing bad documentation: don't delegate it to superseniors working on the project for a long time
- philliphaydon 4y agoBack 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.
- hintymad 4y ago> "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.
- remram 4y agoAlso: if you have to tell me it's simple, rather than showing me examples that make it apparent, I assume it's not.
- wwalexander 4y agoI 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.
- mmcnl 4y agoI 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.
- wwalexander 4y agoSimple 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.
- Brystephor 4y ago> 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.
- chii 4y agoIt'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.
- csydas 4y agoWait 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
- Brystephor 4y agoYep. 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.
- rojobuffalo 4y ago> 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 4y agoThis 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.
- sdoering 4y agoFor those interested here is the original talk the article is referring to: https://youtu.be/9WobKoE9OPI https://youtu.be/9WobKoE9OPI
- 29athrowaway 4y ago1. 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 4y ago> 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).
- nicbou 4y ago10. Structure. Make it easy to find the relevant section and jump to it. Chances are you don't need to read content start to finish.
- 29athrowaway 4y agoOh yes, good point. And format... Format code as code, text as text, math as math.
- euroderf 4y ago> 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.
- AtlasBarfed 4y agoExtracting 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.
- ulisesrmzroche 4y agoNah, this article is poison. Downvote me all you want.
- hahnbee 4y agowhat makes you say that?
- kojeovo 4y agoThought 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 4y agoNot 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.
- ilrwbwrkhv 4y agoThe memcached story https://github.com/memcached/memcached/wiki/TutorialCachingStory https://github.com/memcached/memcached/wiki/TutorialCachingS... is still an iconic piece of dev writing for me.
- powersnail 4y agoAnother 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.
- hinkley 4y agoNot 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.
- nicbou 4y agoIn journalism, they tell you not to bury the lede. In the military, they call for bottom line up front. 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.
- nicbou 4y agoThis is really hard. A few tricks: * 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.
- ag408 4y agoSuper helpful Mason, thank you!
- mmegger 4y agoHey look, I made it to Hacker News. Neat :) Glad y’all enjoyed the presentation and article
- syspec 4y agoWhat 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
- mmcnl 4y agoI 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.
- Apocryphon 4y agoTo be fair, Mr. Egger gave the talk but he did not write the article.
- mmcnl 4y agoI 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.
- murtazakhomusi 4y agoGreat read, 100% agree!
- nomilk 4y agoInsanely 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.
- Master_Odin 4y agoHaving 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.
- nicbou 4y agoThis 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.
- specialist 4y agoYup. 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.
- Seb-C 4y agoI 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.
- bcoughlan 4y agoBuried in the Kubernetes docs is also a link to the API reference https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/ https://kubernetes.io/docs/reference/generated/kubernetes-ap...
- TheJoeMan 4y agoWorse 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.
- dzhiurgis 4y agoNo mention of Docusaurus - the fuzzy api documentation tool that playwright and the like use!?
- nathants 4y agoi’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. 1. https://github.com/nathants/libaws https://github.com/nathants/libaws
- butterNaN 4y agoSurprised no one has mentioned https://documentation.divio.com/ https://documentation.divio.com/ yet