Tag documentation

An ode to well-written READMEs. Detailed, but not overly so, and scannable with examples.

Hey!! Technical writers!! People who do documentation!! I’m a baby in the field and want to know more! What books should I read? What conferences do y’all like? Are there online communities I can join?

grem (@jessica_schalz)Tue, 12 Apr 2022 17:00 +0000

When using Postman, it’s a best practice to store API token values in environment secret variables. Environment variables can also be used to store other variables uses in scripts. But when opening a collection, we often forget to select an environment and spend a few seconds if not minutes or more trying to figure out what the problem is with a request. Just to realize in the end that we just forgot to select an environment. How can this be avoided?

a nice thing about writing with less jargon is that if what I'm saying doesn't make sense, it's easy for readers to call me on it if you use a lot of impenetrable jargon, people will often think the problem is with *them* instead of with your writing

🔎Julia Evans🔍 (@b0rk)Fri, 18 Feb 2022 14:50 GMT

go programmers and the "you don't need to set this to zero or empty string because that's the default value" my dudes... sometimes I want to be explicit for /communication/ reasons. I write code for people, not compilers

Miss Amy (@MissAmyTobey)Thu, 02 Dec 2021 17:43 GMT

I’m genuinely surprised more docs don’t keep their code examples completely separate from their documentation’s prose and embed it in a build step for the output. There are *so many* potential benefits to this.

Tierney Cyren (@bitandbang)Fri, 26 Nov 2021 10:47 GMT

GraphQL APIs are not an excuse to write zero documentation.

Jon Kuperman (@jkup)Sat, 20 Nov 2021 23:14 GMT

"why are your variable names so long?" words are free, my good bitch

Emily Strickland (@emilyst)Thu, 24 Sep 2020 23:53 +0000

I've transitioned from "read docs to learn how to do the thing" to "just give me a repo that does all the things" as my preferred way from picking up a new tool/API. unfortunately, the % of my time that I'm frustrated because the way I want to learn is missing hasn't changed.

Tyranny Siren 🧜🏻 (@bitandbang)Tue, 26 Oct 2021 13:19 +0000

Developers. Please stop referring to the player as “he” in your documentation. Please?

Player 456 (@bengelinas)Mon, 18 Oct 2021 20:58 +0000

https://twitter.com/LadybugPodcast/status/1429923058731687938

In all seriousness, I have to apologise for my bad docs actually causing problems. It's humbling and has caused me become better by increments. More recently I've hurt people by not being clear about expectations for docs, and the why's. It's not easy but that's no excuse.

Pascal Dennerly (@pascaldoesgo)Mon, 23 Aug 2021 21:55 +0000

https://twitter.com/LadybugPodcast/status/1429914958247206920

So. Many. Stories. Do you want ones from my entire 20 year career? Or just this week? It's Monday by the way. And if anyone that knows me reads this, I apologise for the documentation I have written.

Pascal Dennerly (@pascaldoesgo)Mon, 23 Aug 2021 21:38 +0000