Read The Fabulous Manual
by Jay CuthrellShare and discuss on LinkedIn or HN
If you are online in the world of technology, information technology, or anything related to software development — there is a chance you’ve been told in an online forum to “Please RTFM”. Indeed, the RTFM is probably short for Read The @#$%ing Manual.
Me? I prefer to say it means Read The Fabulous Manual.
I’m not alone. 🤓
Getting Informed
What is documentation?
Documentation can seem to be an abstract concept if you are not an IT practitioner or computationally-oriented. As the shopping holiday arrives, a useful analogy for documentation might be the pamphlet of instructions or manual that is commonly ignored and discarded when opening a box with a new technology-infused contraption when you later have a question about how this @#$% thing is supposed to work.
Why does documentaiton matter to people in the real world outside of technolgoy and software?
If you’ve ever heard terms like X10 / Zigbee / Z-wave / HomeAssistant / Apple HomeKit / Amazon Alexa / Google Home / Smartsomething, you’ll enjoy a blog post from Luke Hsiao that caught the eye of many many online forums and newsletters I read: Writing Documentation for Your House.
What does TPS stand for in this context?
If you’ve ever worked in an organization that didn’t have a strong documentarian population, you’ll probably agree that the acronym “TPS” stands for This Place Struggles or This Place Sucks or Tragically Preventable Scenario/Situation. Cover sheets, like documentation, have a higher value by being the latest updated version.
Perhaps you’ve encountered an acronym or backronym for the first time and wondered “WTF”?
(an acronym for “Which Terminology Farce” 😜 )
Searching a git repository for a README.md file or a docs/ folder containing markdown is always appreciated but the effort has to go beyond this:
# COMING SOON
🤣
Arguably, the genesis of companies like SourceGraph was to scratch a common itch among developers for finding the proverbial needle in a haystack in what they refer to as “universal code search”.
Past, Present, and Future
In the time before I was born… as legend has it, some very smart people at IBM named Goldfarb, Mosher and Lorie were fond of backronyms and also were responsible for crafting something that came to be called Generalized Markup Langage (GML). Oh, the date? Well, assuming I live a bit longer, I’m turning 52 years of age soon! 👴
Now, to avoid becoming encyclopedic in length, I’ll simply say that in the beginning, GML became a Standard known as SGML, and there was eXtensible Markup Language (XML) as well as the Document Type Definition (DTD). Then some really neat stuff happened in between then and now in the land of technical writing and the ethos of the documentarian within an increasingly software application oriented world.
Roughly 32 years ago, the notion of a portable self-contained documentation schema project came to life: DocBook (1991)
A lot can happen in 32 years. For example, many modern interwebs technologies didn’t exist in 1991 and, these days, I no longer require a hair stylist. 🧑🦲
The great thing about standards
If you consider standards bodies, one reference that comes up from time to time is OASIS (1993) which formed around this same time under what might sound like a slightly more nerdy name, “SGML OPEN” (unless you were following various markup languages of the day and “SGML OPEN” would seem very normal naming).
Well, along came the Darwin Information Typing Architecture (DITA) a few years later and has reached the voting age in the USA. Additionally, there is even a DITA Open Toolkit community.
Just over three decades ago, the concept of Auto-Updating as a Technical Documentation Tool (1988) was posed by the author of Thinking Like a Computer (2020) and Digital Reality (2018). Similarly, around a decade ago, the topic of Automatic Documentation Generation from Source Code was and remains a consistent research topic.
Surely, the machines could easily infer what was being coded within the mindset and intention of a developer then expand it and explain it in plain language, right? Encoder and decoder bingo bango bongo – and all before the current hype cycle around A.I. and Large Language Marmalade (L.L.M.) came into the zeitgeist.
Going deeper…
To understand the future of technical documentation, Slack and Discord communities are often good deep web options for learning more about what’s happening in the practitioner space. These Slack and Discord communities attract practitioners within product led growth strategy companies that embrace Digital Adoption Platform (DAP) principles and share tradecraft across tools, techniques, tips, and their evolving methodologies.
For example…
Now, let’s take a quick non-exhaustive appraisal of what’s happening in the technical documentation tooling space around DocOps and Docs as Code.
Recent
- What Is Good Documentation, Anyway? (2020)
- Previously in Fudge Sunday: DevCommsOps (2021)
- Confluence Usage Year in Review (2022)
- Automatic Code Documentation Generation (2022)
Latest
- Read The Docs Roadmap
- swimm’s new AI offering (beta)
- Beyond DITA vs. DocBook
- Developer Hub for Amazon API Gateway
- Don’t Be Afraid of the Docs!
- Docusaurus 3.0
- AsyncAPI Docs Report
- Cookbook for better Redocly CLI recipes
- Autogenerating API documentation from OpenAPI
- Mastering Automation Through the Power of Documentation
- Instant API documentation with Postbot
Product Hunt buzz related launches
While this newsletter can only scratch the surface of the amazing things happening in the technical documentation community, it’s worth noting the perfect team is still one to do it, one to write it down, and one to think ahead.
One theme that will become increasingly common in the OpenAPI community (note: that’s OpenAPI not OpenAI) is the automatic generation of documentation as with OpenAPI Generator and R.A.G. + L.L.M. solutions such as bots that continuously crawl documentation repositories to provide modern accessible end user experiences within the context of a software application — and, eventually, consumer-grade technology infused contraptions that will (literally) tell you how the @#$% thing is supposed to work.
That’s right. The humble kitchen gadget blinking 12:00 may one day become more than just knobs, buttons, and the missing documentation that was tossed away with its cardboard box — and (literally) tell you that you are holding it wrong.
Or, perhaps it will be a network appliance first… and then a household appliance. We shall see.
Convergence in network automation is climbing the Y-axis of a Wardley map. – Jay Cuthrell
Source: LinkedIn
So, what will be the next big thing in DocOps, AI-assisted documentation, AI-infused autogeneration of documentation, and the role of human-machine augmentation partnerships in making delightful documentation within fabulous manuals?
Until then… Place your bets!
Disclosure
I am linking to my disclosure.
Topics:
✍️ 🤓 Edit on Github 🐙 ✍️
Share and discuss on LinkedIn or HN
-
Get Fudge Sunday each week