We added a "Release Notes" field to Jira as part of a project to automate release comms. Devs & QA folks are using it a lot. This unpromoted field is seeing better adoption than anything else we've rolled out ever. Now to rename to "User Release Notes" to scare folks away & maybe add "Engineering Release Notes" to keep the momentum up.
Administered by:
#technicalwriting
4 posts3 participants2 posts today
I spent 3 hours "fixing" a feature that hadn't been documented sufficiently… in my own scripts. It is very well documented now.
Ok, I really like this widget idea for #TechnicalWriting
A button that I can always click to bring up a clickable table of contents. Useful in long factual documents where you just want to jump to another part of the page.
Hate that it's floating at the bottom of the page, but…
AI stands for “Artificial Inanity”: https://lambdaland.org/posts/2025-08-04_artifical_inanity/
This short post recants my own feelings about reading AI-generated text: it's exhausting, simply because it's text created without human intent and care. Probability is not thinking; probability is not care; popular AI systems that generate text are just probability engines trained on old text.
Texts that are generated by popular AI systems often feel *off*, which is highly important to humans.
Feeling good this morning. Yesterday was my last day in the office before I get retrenched next Wednesday. I curated the day, catching up with some wonderful people who have brought joy to my time in the organisation, then I left really early.
For the next few days I am making use of the training material the organisation provides before returning my equipment for final sign out next Wednesday.
I don't have a new job, but am applying for roles and am working on a possible business idea that seems to have legs. Over the last 3 years I have been networking and doing the right things so I feel something will turn up. Importantly, I have a plan of action.
The most important thing is that I keep my mood up. 100% remote work just doesn't work for me - I get mouldy sitting by myself in a home office all the time. So I have found a cafe that has lots of space and not enough customers where I can work for an hour or so each day. I also have allowed myself a daily coffee budget.
If you know of any #TechnicalWriting, general management and user experience or customer success roles going in #Melbourne, feel free to let me know. I am open to contract or permanent, full-time or part-time.
"[W]hat we are doing is shepherding AI, limiting it to certain contexts. We are learning where it’s best to call it, how is best to feed it. And what to do with the output. So is it looks very much like an editorial process, an editorial workflow where you provide some initial input, maybe some some idea on what content to produce, then you review it. There’s always that quality assurance, quality control side, the supervision.
AI is not really autonomous. It relies a lot on us. And I feel like sometimes there are days where, when coding through AIs or doing some assisted writing, I’m spending more time helping out the AI doing the actual task that I’m asking the AI to do. But I take this as a learning process. I read this article the other day, Nobody knows how to build with AI yet. And it was a developer saying that they haven’t quite figured out how to best work with AI. There were lots of comments around the fact that you have to spend lots of time, you have to learn how to talk to it, and when the model changes, you have to also maybe change something you’re doing. You have to learn how to optimize your time. But your presence is always mandatory.”
passo.uno · Webinar: What's Wrong with AI Generated DocsToday I discussed how tech writers can use AI at work with Tom Johnson and Scott Abel. It all started from my post What’s wrong with AI-generated docs, though we didn’t just focus on the negatives; in fact, we ended up acknowledging that, while AI has limitations, it’s also the most powerful productivity tool at our disposal. Here are some of the things I said during the webinar, transcribed and edited for clarity.
"While haste and speed often get confused, they differ in that the second shows control instead of panic. You can maximize speed while keeping accuracy quite high; beyond a certain point, though, spending more time on accuracy, style, or other aspects that prevent a document from going live always yields diminishing returns.
Nobody reads perfect yet outdated docs, except historians. Even then, docs aren’t perfect, because documentation can’t ever be perfect. This is a key principle I stand by (call it the Ferri Paradox if you want): Any document describing a system is necessarily inaccurate. And yet, this reality doesn’t significantly alter the impact of our work, because we aim for simplicity and usefulness over extreme faithfulness. Given how imperfect products are, docs are a charitable portrait.
Now, how you write docs quickly depends on a number of factors. Some of those factors you can’t control: your overall amount of experience as a writer, your initial expertise with specific technologies, and the way features are developed and released in your organization. But other aspects are yours to act upon. For example, you can decide how to best use the technical resources at your disposal and how to approach writing the docs and asking for feedback."
passo.uno · How I write docs quicklyI’ve been writing documentation and technical articles for more than a decade now. One piece of feedback I consistently got from managers and peers during all these years is how fast I am when producing and releasing docs. For example, I was once asked to document a new feature from a team I wasn’t serving two weeks ahead of launch. Everything was new to me, but I had most of the docs drafted after four days. By launch, the docs had been deemed ready to go live.
Basic Questions That Every (Technical) Writer Should Try To Answer - AKA Technical Writing 101:
I assure you that If you can answer all of these questions, your readers won't mistake you for a chatbot :)
1. What is the purpose of the document that I'm writing?
2. Why am I writing this document?
3. Who is the target audience of this document?
4. Is this document part of a series of documents?
5. If so, have I established a nexus to the other documents in the series?
6. Are there any predefined formal requirements that the document must meet?
7. Does the document meet those requirements?
8. Does the document include an introduction?
9. Does the introduction clearly explain the purpose of the document to the target audience?
10. Does the introduction present the topics that will be explored in the body of the document in a straightforward way?
11. Does the document include a conclusion?
12. Does the conclusion provide a good summary of the previously explored topics?
13. Does the conclusion tell readers what they should have learned by following the document?
14. Does the body of the document include use case scenarios based on user personas that explain the potential advantages of adopting the explored tools or methods?
15. Does the body of the document depict real-life examples of how readers can immediately start using the tools or methods explained in the document?
She is Still Looking For Work - Celeste Seberras, Tech Writer / Content Strategist / Developer Relations with a Infosec and entrepreneurial background. http://resume.hakr.gg http://lnkd.in/gYRfjTcB #AI #Blockchain #Infosec #Cybersecurity #TechnicalWriting #developerrelations
resume.hakr.ggresume.hakr.gg | jaruga's resume
"[Techimabob-thingy] is powered by AI, so mistakes are possible. Review output carefully before use." Right. In decades of tech writing my experience proves folks are super careful & thorough when reviewing anything, esp. their "own" work.
Elevate your communication skills and make your points impossible to ignore.
youtu.be- YouTubeEnjoy the videos and music you love, upload original content, and share it all with friends, family, and the world on YouTube.
Continued thread
I’m doing the Instant Pot test run following the user manual. The user manual is very good—I mean speaking as a professional it’s excellent technical writing. I would use this manual to teach a class in how to do it right. #TechnicalWriting
#cooking #food
"The purpose of documentation is to skill and empower someone in their craft. It serves their acquisition and application of skill.
I have heard it suggested that documentation should now be optimised for consumption by AI. That is like asking how we can make our cities better for cars, or our workplaces better for the furniture.
If creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.
Even if we think about the notion only pragmatically, leaving all values aside, it’s a panicky, inconsidered idea. What possible sense does it make to try to “write for LLMs” when LLMs themselves are evolving so rapidly that their capacities and patterns change from one week to the next?
Human beings are difficult creatures with complex needs, but they have been that kind of creature for thousands of years. Not only have we painstakingly built up deep understanding of them, we are them; we can know them from the inside. A good way of writing documentation for human beings today will still be a good way to do it in a few years’ time."
vurt.orgMy favourite German word - Daniele ProcidaIf creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.
#Documentation That Developers Actually Read: The Netflix Approach - DEV Community
https://dev.to/teamcamp/documentation-that-developers-actually-read-the-netflix-approach-1h9i
DEV CommunityDocumentation That Developers Actually Read: The Netflix Approach"Our documentation is our product's UI for developers." - Netflix Engineering Team. Let's be...
My second video, which if I'm honest is probably the best advice I can give to any one on communication.
Tired Of Unanswered Emails? Try This!
https://youtu.be/bmm38OFzbVQ
“The goal from starting out is to be able to create an API documentation suite from scratch. The minimal viable document, or the minimum the document must contain before it’s released, includes having all the calls covered, a description, even if only one sentence at this point, for every field and call, section overviews, call examples, and examples of each field. I suggest also creating a Postman collection file for each API suite. A Postman collection file is a complete set of all the requests and that each request may be run by clicking it; it’s a convenience to clients.
Being able to create that document indicates the writer’s proficiency in the mechanics of API documentation. There is a sense of accomplishment when achieving this and comfort with this process. And rightly so. They have the privilege now of calling themselves API documentation writers.”
Medium · Starting API Documentation Writers: Obstacles To Watch Out For
"What are docs for AI agents? How are they different than internal eng docs? Do we really have to maintain the agent docs and eng docs as separate docs sets? This page contains my notes on these questions.
Scope:
I work on developer docs i.e. docs for software engineers. I don’t know how relevant AI agents are for technical writers in other industries or domains.
I’m thinking specifically about docs for AI agents. I’m not sure that an all-encompassing “docs for AI best practices” exists. The way that we optimize docs for RAG-based chatbots (for example) is probably different than the way we optimize docs for AI agents."
technicalwriting.devDocs for AI agents
My first video on YouTube for The Technical Editor.
"Stop Explaining Things Wrong—Do This Instead"
Most engineers skip the #1 rule of technical communication.
Spoiler: It’s not about what you say, but who’s reading it.
youtu.be- YouTubeEnjoy the videos and music you love, upload original content, and share it all with friends, family, and the world on YouTube.
Poor example to introduce the `disabled` HTML attribute:
Lesson: Don't use the same/similar name as the concept being introduced.
```html
<label>
<input type="checkbox" name="ch-box" value="disabled" disabled />
disabled
</label>
```
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled#examples
MDN Web DocsHTML attribute: disabled - HTML | MDNThe Boolean disabled attribute, when present, makes the element not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants.