Can’t tell you how infuriating it is to find #Streaming distributors pulling the same crap on #Documentarians and #Filmmakers as they are on #Musicians and #Composers. We know what this is. Just add #AI claims on *TrainingAsFairUse* to put the icing on the new forever #Cesspool cake.
#Disgusting
#Documentarians
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?
Today I was musing about how we as #TechnicalWriters know when to update documentation. Are there strategies you use to find out about changes to the product? Do you rely on stakeholders to tell you about upcoming changes? Are you embedded on teams where you're involved in planning and can decide for yourself when to update docs?
I had a few thoughts based on how I do things, but I'm really curious how other #Documentarians approach this challenge.
https://dacharycarey.com/2023/10/18/knowing-when-docs-need-updates/
Ok, #documentarians and #TechnicalWriters of the Fedi - how do you handle docs feedback?
1) Do you have a way for readers to leave docs feedback? How does it work?
2) Do your readers actually leave feedback?
3) How does that feedback come to your team?
4) What do you do with it?
5) Do other stakeholders in the org see feedback?
6) Have you found type and frequency of feedback change over time in a way that seems to correlate with your docs work?
Threading my replies - looking forward to yours!
Finally added this account to Fedilab so now I can check it at times other than just when I'm on my computer, lol. Look forward to a lot more interaction! (I'll try to keep it #contentCreator-centric, and keep my off-topic replies on my personal account.)
If you're a content creator with a focus on #antiPatriarchy, #antiDiscrimination and/or #antiCapitalism #activism and you'd like us to boost your content, please follow us and leave a summary of your content in the replies! Open to #videoEssays, #vloggers, #documentarians, #artists, #writers, #podcasters, #bloggers, and all else--you just have to be a content creator, or supporter of content creators, that won't be rude towards creators who don't fit neatly into the family-safe, ad-friendly world of mainstream accounts.
The focus of OCC is to uplift and support so-called "outcast creators," those of us who create content that is not welcome on most mainstream platforms and thus very often gets #censored and #shadowbanned. We're not a place to just show up, dump links to your content, then leave--we're a community, with active participation and forging friendships.
We also have a new discord server that we're slowly growing - - here's an invite link if you'd like to check it out! https://discord.gg/vbMYZM6b
The largest #photography #library in Africa has opened in #Ghana ’s capital, #Accra , #showcasing the work of the continent and #diaspora ’s forgotten, established & emerging talent.
The #DikanCenter offers a #PhotoStudio & #classrooms provide space for #workshops while a #fellowship programme is aimed at #African #documentarians and #VisualArtists.
#GoodNews #BlackMastodon #POC #Progressive #CommunityBuilding #education #opportunities #CreativeArtists #Africa
Client Info
Server: https://mastodon.social
Version: 2025.07
Repository: https://github.com/cyevgeniy/lmst