A little something for the #Documentarians and #TechnicalWriters
How to add the #Vale text linter to your project, a quick start.
https://alecthegeek.gitlab.io/blog/2024/04/add-vale-to-your-project/
Continuing the series about testing the code examples in documentation, I've just put up a post about *what* to test in docs code examples.
Spoiler alert: it might be both more and less than you think!
https://dacharycarey.com/2024/02/11/what-to-test-in-docs-code-examples/
When you are writing docs for developers, please do not hide away content under arbitrary headings that are not easily understood by your readers! Present info in a way that even readers who are new to your product can understand. Avoid feature names, too, unless they are common terms in the industry.
An argument can be made either way for organizing based on topic or task, but those are both good choices to make information easily discoverable to readers.
It took me way too long to convince my teammates that we needed to change how we organize the information to make it more discoverable for the devs who use our product. But when I did, we re-integrated Fundamental content onto the task-based Usage Examples pages and entire classes of negative docs feedback went away. People saw the info they needed in the context where they needed it. Amazing!
We also changed the hierarchy and suddenly content was visible!
When I started at current job, our docs were divided into “Fundamentals,” “Usage Examples,” and “Advanced.”
Nobody read the Fundamentals. The division between Usage Examples and Advanced was completely arbitrary. People went directly to Usage Examples and totally missed important info that was in these other very arbitrary sections.
There were topics in “Advanced” that we say literally every production app should do. That can’t be Advanced!
Related, Pkl and many other dev docs sets do something I absolutely abhor: using “Advanced” as an arbitrary heading for some subset of the content. In 99.99% of the cases, that becomes a catch-all for stuff that should be surfaced in some other way. It’s a junk drawer.
Also, it’s a horrible heading. Pkl is brand new. Nobody is “Advanced.” Is your use case “Advanced?” How will you know when you first encounter this thing? It just hides content away.
I shared the Pkl documentation with spousey: https://pkl-lang.org/main/current/index.html
It’s always interesting watching her reaction to dev docs. She has strong opinions and it was disheartening how quickly she didn’t find what she thought should be there and completely bounced off the docs.
I happen to *know* the info she’s looking for IS there because I already clicked around.
#Documentarians and #TechnicalWriters - it doesn’t matter how good and comprehensive your info is if your readers can’t find it.
I finally made time to write about *how* to test code examples for documentation. This is a high-level overview of how my team tests the code examples that we include in our documentation for correctness and accuracy:
- Write the tests in idiomatic unit test suites
- Excerpt example code for inclusion in docs
- Include example code in the docs
- Run docs tests in CI
I'd love to hear how any of you other docs folks handle this!
#Documentarians #TechnicalWriting
https://dacharycarey.com/2024/01/12/how-to-test-docs-code-examples/
I am working on a new Information Architecture for our product documentation to better align with changes in market strategy.
I created a new “Quick Start” that brings together bits from a few different documents. It’s a better comprehensive overview now, but is far from “quick.”
#TechnicalWriters and #Documentarians - do you have any strategies for managing complexity in your docs? Abby Covert’s books are excellent. Any other good practical guides?
KilleansRow 🇺🇲 🇺🇦🍀
Alec 
🇦🇺 👨💻
Dachary
