Doc Detective

I'm so happy to be a highlighted open source maintainer over at GitHub! If you're curious how and why I made Doc Detective open source, check out the feature! (?? in comments)

Just 2 months until Write the Docs Portland 2025. ?? Who else is counting down to May 4-6 at Revolution Hall? We’re excited to announce we’re hosting pre-conference speaker discussions, have added a virtual ticket option, and Writing Day submissions are now open. View all the latest news below. https://lnkd.in/gyujNgAd

I feel that code samples in API docs are just as important as ever, though maybe not for the reasons you're thinking. We need code samples for API and docs reliability. Reading through Tom Johnson's recent post about code samples in API docs (?? in comment), I was struck by the following passage: "Overall I sensed that, while code samples were a “nice to have,” developers didn’t actually need them anymore. Internal devs also argued that adding the code samples into the docs would also create a maintenance burden, as they could easily go out of date with API changes." Code samples should be in the docs because they're a maintenance **benefit**. With a #DocsAsTests approach, code samples in docs become executable and verifiable. Your docs—acting as tests—let you know when they stop working with the API so you can get the docs updated. Bring on the API changes. Docs are your early warning system for breaking changes. It might be difficult to set up some code samples, like for gRPC APIs. I get it. But we should be willing to perform the tasks we ask of our readers. If we can take that time, asking for the help and bandwidth when we need it, our docs become a better resource for our readers by showing them a known-good implementation, and we writers get reliable, testable docs. A bit of up-front investment, but win-win in the long-term. Also, the post suggests that AI could easily come up with relevant code samples from an API description. This is true. But the generated code would be as fragile as the API description it came from. I've come across some loosely defined APIs (including some of my own at Google). Working from one of those, an AI might generate code that matched the description but failed in execution because an expectation wasn't as clearly or strictly defined as it might've been. Not an ideal user experience. Ask me how I know. I agree with Tom that simple and obvious examples are okay. They're often just what users need. But users do **need** samples. For all the normal developer experience reasons. Because they improve AI output. Because they keep the API implementation honest and current. Because samples are a docs maintenance benefit, not a burden.

Screenshots and videos can be great visual aids for your customers, but only when they're current! SaaS product UIs can change fairly often, so regularly reviewing and updating the visual content in your knowledge base is key to giving your customers an exceptional self-service experience.

We are excited to announce the speakers for the 2025 Portland Conference! ??? Each year, we strive to bring a diverse array of voices and topics that cover practical, philosophical, and technical ideas – with a sprinkle of whimsy :) View the full list: https://lnkd.in/eCVM-Jhg ??? May 4-6, 2025 #writethedocs