Readit News logoReadit News
johnathandos commented on Markdown is holding you back   newsletter.bphogan.com/ar... · Posted by u/zdw
johnathandos · a month ago
It’s good to spread awareness (or just remind folks) that alternatives to Markdown exist. The right tool for the job depends on your circumstances. If I were scaling a docset for a team of contributors primarily consisting of technical writers, .adoc or .rst would be my preference. If I were scaling internal docs-as-code infra for software engineers, I’d use Markdown.
johnathandos commented on Docs like code in basic terms   deborahwrites.com/blog/do... · Posted by u/DeborahWrites
lproven · 8 months ago
> it's a widely-used term/practice in tech writing

But it's not. You have got the key phrase wrong!

It's Docs as Code.

There are whole websites devoted to it:

https://docsascode.org/

Not "like": As -- meaning, "create docs as you create code", meaning "using the same tools and methods."

There is a good strong evidence that your version is inferior: the dozens of comments in this thread by people baffled by the phrase, or pointing out its flawed construction.

It's the Docs As Code approach, _NOT_ "docs like code".

https://docascod.github.io/howto/#/

https://marketplace.visualstudio.com/items?itemName=rafaelmn...

https://www.synesthesia.co.uk/tag/docsascode/

johnathandos · 8 months ago
This really depends on where you first encountered the term. Anne Gentle wrote Docs Like Code, the first book I read on this topic 8 years ago. I always consider the terms "docs as code" and "docs like code" to be interchangeable, and usually use both when discussing the topic with an audience that includes a wide variety of different individuals. I think "docs as code" is probably used more in purely dev circles due to the proliferation of the "everything-as-code" construction seen in other dev-adjacent disciplines (infra-as-code, config-as-code, etc.)
johnathandos commented on Focus on decisions, not tasks   technicalwriting.dev/stra... · Posted by u/kaycebasques
kaycebasques · a year ago
You're getting a taste of the world that a lot of professional technical writers live in. Everyone seems to intuitively understand that you need docs, and that if you don't invest in docs it probably will be bad for the business, yet at the same time it's hard to concretely show business value. So technical writers are incessantly asked to prove their value, even though the managers subconsciously know that they're important for some reason. Over the years I have come to believe that docs are important simply because it's a primary mechanism for sharing knowledge across the company and to customers. Michelle Irvine has been doing great work quantifying this: https://cloud.google.com/blog/products/devops-sre/deep-dive-...
johnathandos · a year ago
Thanks for sharing this post from Michelle, just shared it with some leaders at my company!
johnathandos commented on Focus on decisions, not tasks   technicalwriting.dev/stra... · Posted by u/kaycebasques
auggierose · a year ago
Interesting that your first thought here is not, oh, how can I use this to improve the docs I am writing, but it is, how can I prove that this improves the docs I am writing. You seem to live in a though environment.
johnathandos · a year ago
You're not wrong. Business is a tough environment.

At a gut level the post seems sensible to me, and it does generate a lot of ideas about how I can make my own docs better. That's not enough, though, if I want the folks who think about docs at my org to change their approach.

As the OP states in several other comments, most writers and organizations learn to prioritize task-based documentation. If we want to adopt a better way of doing things, we need to be able to communicate why it's better. It's no different in other disciplines.

johnathandos commented on Focus on decisions, not tasks   technicalwriting.dev/stra... · Posted by u/kaycebasques
johnathandos · a year ago
Thanks for sharing. A couple of thoughts.

It seems like it's a lot harder to measure whether your docs are helping people make good decisions than it is to measure whether they are helping people successfully accomplish a task. I think we optimize for task-based/procedural docs because the business needs us to prove our value, and there is a need for this type of documentation, and there are lots of ways to measure and report on it over short timelines. But answering the question of, "Did this docset help someone build the right thing in the right way", I mean...organizations struggle to answer this question about their own products, abstracting that to try and measure the effectiveness of your docs seems super fuzzy.

Which is not to say you can't write docs that do this, just that it seems very hard to use numbers to prove that you have done so. I definitely think I could rank how well different docsets support users who need to make decisions, and I could offer up explanations to support my reasoning, but I don't know how to quantify that for the business.

I wonder how the structure of a docset that is designed to support decisions differs from that of a docset that supports tasks. I expect you'll have the same main categories (conceptual, reference, guides) but maybe a lot more conceptual docs, and more space dedicated to contextualizing the concepts. I would expect to see topics become more interdependent, more cross-references, etc.

johnathandos commented on Sleep duration, chronotype, health and lifestyle factors affect cognition [pdf]   bmjpublichealth.bmj.com/c... · Posted by u/susam
gonzo41 · a year ago
What if you're a night owl who sleeps in. Does that make you just an offset normie?
johnathandos · a year ago
Aren’t we all just offset normies?
johnathandos commented on Serverless Video Transcription inspired by Cyberpunk 2077   github.com/elanmart/cbp-t... · Posted by u/pierremenard
coding123 · 3 years ago
I think part of the magic is still lost, as we used to be very open source and free centric. These days it's all based on paid API calls.
johnathandos · 3 years ago
Someone is out there building and maintaining the APIs

u/johnathandos

KarmaCake day39March 1, 2020
About
https://johnathandos.com/
View Original