So, the company where I work has 'pivoted' to a new product and we no longer build the thing that we used to build. Today I delete the website where I build 70 (seventy!) docs releases since May 2021. #TechnicalWriting sucks sometimes.
Farewell then r2021.05, v1.35.0, and all the versions between...
The pushback against AI slop is making employers recognise the importance of skilled writing by humans so they are now hiring "storytellers":
"It’s so much more than a copywriter,” says one hirer: https://www.wsj.com/articles/companies-are-desperately-seeking-storytellers-7b79f54e
Hopefully this will see a move beyond hiring copywriters to keyword stuff for SEO and AI, a move beyond judging skill by simplistic metrics such as number of boosts, likes etc. I hope that organisations will want professional writers who can identify target audiences and deliver meaningful material that will be valued by those audiences. This is true success, but may mean that the post or article might not get many clicks.
I hope that over time "storyteller" will not simply become a synonym for "copywriter".
Technical writers already provide this kind of skill when writing about technology, or health, or science, or digital humanities
#WriteTheDocs #TechWriting #TechnicalWriting #TechnicalWriters #DigitalHumanities
I'm converting a 400-page PDF file to Markdown via marker-pdf. It looks like it'll clock in at 6.5 hours to complete...hopefully!
Marker is the best PDF-to-Markdown converter I've found, hands down: https://github.com/datalab-to/marker
#marker #marker-pdf #conversion #pdf #Markdown #TechnicalWriting #conversion
This is so obvious, yet at the same time it seems to me that people rarely really understand what is at stake.
"Most of the breakdowns in a product don’t come from bad intentions or bad work. They come from the way teams divide responsibilities. Engineering focuses on the system behavior. Design focuses on screens and interaction. Product focuses on requirements and scope. Each group works inside its own boundary, and no one is responsible for checking whether all those boundaries line up.
That’s how you end up with a feature that technically “works,” but only if the user magically knows the right order of steps, or already understands a concept that was never explained, or follows a path that only makes sense inside one team’s mental model.
The writer is the first person who has to confront that reality. Not because we’re smarter—because documentation forces us to walk the entire experience in the same order the user will. No shortcuts. No inherited assumptions. No internal knowledge. Just: If I follow this from beginning to end, does it hold together?
That’s when the real gaps surface:
- Prerequisite steps that were never shown in the UI, but the system silently requires.
- Terminology drift where three teams named the same thing differently and nobody noticed.
- Logic branches that exist in engineering’s head, but not in the design or the workflow.
- Error states with no recovery, dropping users into dead ends no one tested.
- Hidden dependencies, like expecting users to configure something before they even have access to it.
- Contradictory steps created by teams working from different assumptions about how something is “supposed” to work.
None of these are “documentation problems.” They’re structural problems that documentation exposes because documentation is the first time anyone tries to describe the system as one connected experience."
https://brandihopkins.com/involve-writers-early/
#TechnicalWriting #SoftwareDevelopment #SoftwareDocumentation #DocsAsProduct #UX
I'm honestly not sure up to what extent the output to the context-enriched prompt is better than the output generated as a response to the contextless prompt, specially since the context-enriched version seems to be essentially a series of lists...
"Have you ever tried prompting an LLM to write documentation for you, only to notice the prompt has become longer than the page you need to write?
This is because authors have lots to requirements to consider when creating documentation: style guidelines, content types and templates, branding, publishing and formatting requirements, and much more.
In Part 3 of this series, we learned how to use prompts and commands to instruct Gemini CLI to follow a specific set of style guidelines. Today, we’ll take it a step further by giving Gemini even more context using a GEMINI.md file. We’ll also try prompting Gemini with and without the file, to ensure we’ve engineered this context in the most effective way possible (also known as “A/B” testing).
If you haven’t heard of “context engineering”, it’s basically about writing instructional content and building a content strategy for LLMs. That’s why I personally think that technical writers are destined to be incredible context engineers."
#TechnicalWriting #PromptEngineering #ContextEngineering #Gemini #GeminiCLI #AI #GenerativeAI #SoftwareDocumentation
"At my current job, I've built a CLI tool that has over 20 different commands that help my team with doc ops and content quality. We frequently add, remove, and refine commands as our approach to documentation matures and our tooling changes. Our CLI was built to work with our docs repo, and has tools that let us do things like:
- Validate all our arbitrary frontmatter
- Generate card components for individual pages from frontmatter
- Regenerate our custom Vale Views
- Run a bunch of git commands for reporting purposes
- Build a changelog for our Fern Definition
- Summarize changes on a branch compared to main (to help draft release notes)
- Extract and format a list of all our public endpoints from our Fern Definition
- Generate a list of slugs and their associated filenames
- Regenerate all D2 diagrams
- Preflight checks that run all of our doc quality checks
- So much more
Some of our commands are just thin wrappers for commands for other tools we use (like Fern, Vale, git, and Linkinator). Some of our commands are just wrappers for bundles of our homegrown scripts. There aren't any hard rules for building your own internal CLI tooling. I just happened to bundle it all up into a CLI tool because that's what made sense for my team. Do what makes sense for your team."
https://docsgoblin.com/blog/25-12-03-building-tooling.html
#TechnicalWriting #DocsAsCode #Automation #SoftwareDocumentation #CLI #DocOps #Git #Vale
"Visual IDEs vs CLIs: For documentation, visual IDEs (like Antigravity or Cursor) are preferred over CLI tools because writers need to see the diffs and iterate conversationally, whereas CLI tools are often better for pure code generation.
The “good base” requirement: AI tools like Claude can generate 70% complete drafts when provided with rich context, but this relies heavily on having a strong, existing foundation of documentation to “seed” the model or RAG system.
Documentation theater: Auto-generated “code wikis” can create a dangerous illusion of documentation (“documentation theater”)—they capture the what and how from code but miss the critical why and product appraisal that users need.
Transparency dilemmas: While disclosing AI usage promotes a culture of learning and honesty, it risks being misinterpreted by leadership as “push-button” work, potentially devaluing the human effort involved in prompting, refining, and verifying.
The review bottleneck: AI accelerates content generation but exacerbates the review bottleneck. To manage this, use “dumb robots” (linters) for basics and “smart robots” (AI) for initial reviews, and maintain strict PR hygiene (small, manageable changes).
Redefining productivity: Traditional metrics like PR counts are misleading in an AI world where volume is cheap. True productivity should be measured by the value delivered—unblocking teams, enabling contributions, and focusing on strategic architecture rather than just “plumbing” fixes."
https://idratherbewriting.com/blog/podcast-episode-3-documentation-theater-acceleration-paradox
#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #DocumentationTheater #SoftwareDevelopment #Automation #Productivity
Adventures in technical writing: I just caught this typo in a draft:
"Shite+Win+S (Windows)"
Freudian slip?
Doplnil jsem ke kurzům, které jsem vytvořil pro Apify, testy, aby mi pravidelně kontrolovaly, jestli jsou v nich praktická cvičení funkční.
Testy běhají moc pěkně, takže jsem to teda opravdu zjistil, jestli jsou ta praktická cvičení funkční…
"Designed well, a knowledge base ensures agents have access to up-to-date and comprehensive organizational knowledge. Ultimately, this improves the consistency, accuracy, responsiveness, and governance of agentic responses and actions.
The benefits are clear. But what actually goes into such a repository?
(...)
A knowledge base for AI agents can hold many things: documentation, policies, style guides, sample code, workflows, compliance rules, and more. “A knowledge base for AI agents contains the full spectrum of a company’s operational reality,” says Igor Beninca, data science manager at Indicium, a data and AI services firm.
Because enterprise data varies widely, a knowledge base will combine structured, semi-structured, and unstructured data. It should span everything from static rules to dynamic chat conversations. Really, any data that could be vectorized for training AI is fair game. That said, some common content types shine through for AI agent use cases."
https://www.infoworld.com/article/4091400/anatomy-of-an-ai-agent-knowledge-base.html
#AI #GenerativeAI #AIAgents #AgenticAI #KnowledgeBase #TechnicalWriting #SoftwareDocumentation
"AI tools are moving the floor up. There’s more being expected of writers and I worry that junior roles, just like they are in engineering, are going away.
The basis of the craft is changing. Being a good writer, whatever the field, takes time and training. It’s a field of instruction, pedagogy, information stewardship. It’s part marketing, education, support, and engineering. By definition, it is different from being an engineer, but now that market is demanding both roles in one. This is a new, demanding environment and market.
I think we need to think very differently about what a technical writer role is and pivot accordingly. I’ve seen many people writing about AI tools, and yes, that’s great. But there is a huge opportunity for us to think bigger about this role and at a top level: What does a full stack docs strategy (and yes here are some AI tools to help build that). What does it mean to help build a unified data model for APIs? What information architectures do different docs portals need and how can we implement front-ends to maximize that structure for the best-in-class user experiences (leverage AI accordingly)? DocsX (docs experience) now has to be considered a full stack problem. So let’s get to it."
https://medium.com/@anandi.silva.knuppel/the-engineering-of-the-technical-writer-89092b609cf0
#TechnicalWriting #AI #GenerativeAI #TechnicalCommunication #DocumentationEngineer #DocsX #FullStack #SoftwareDocumentation
"Over the past few months, I’ve been talking with folks about how they find information and learn about a product. ChatGPT and Claude and Gemini (or at least Google’s “AI overview”) are consistently mentioned as one of the main methods people use. Even if the output isn’t that reliable, visiting an AI tool is still a key part of the information-finding flow.
AI tools are used for all sorts of information-finding flows:
- Answering basic questions about how to accomplish a task.
- Decipher the potential root cause of an error message and provide next steps for resolution.
- Provide solutions to intricate application design questions.
- Suggest syntax for code, a formula, or a SQL statement.
You need an AI strategy for your documentation to enable customers using AI to be more successful when using your product to accomplish their goals.
The components of an effective AI strategy include the following:
- Develop: Partner with teams building AI into your product.
- Discover: Evaluate and improve your content and content strategy.
- Measure: Measure how people use AI to interact with your documentation.
- Adapt: Explore use cases for AI in your documentation practice."
https://thisisimportant.net/posts/ai-strategy-for-documentation/
#AI #GenerativeAI #Chatbots #AIAgents #TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #ContentStrategy
This distinction is key. Only human beings can assign a purpose to a text. And only other human beings can understand that purpose. Purposeless, meaningless texts are external to this world. Perhaps in five thousand years, there will be entities capable of assimilating automatically generated texts in order to produce something entirely new of their own free will. Until then, writing and reading will only make sense when referring to human beings as the subjects.
"Simply put, AI may understand the act of writing, in a very limited way, but it does not understand the act of reading what has been written. As someone who has read and edited literally tens of thousands of pages of technical documentation, and thousands of pages of student essays during my career in higher ed, I can tell you that there are good writers, okay writers, and terrible writers. What distinguishes them is those who understand reading as a cognitive act that is intended to produce an effect in the mind of the reader, and those who don’t."
https://www.linkedin.com/pulse/limitations-ai-writing-kai-alvason-phd-8ig0c/
#AI #GenerativeAI #Writing #Reading #Documentation #Docs #SoftwareDocumentation #TechnicalWriting
Seems legit... I've started to use it and it has been a great help when browsing a huge Git repository Vs doing the same over OxigenXML.
"DitaCraft is a lightweight extension that brings DITA support directly into VS Code, one of the most popular code editors. It provides:
- Syntax highlighting for .dita, .ditamap, and .bookmap files.
Real-time validation against DITA 1.3 standards.
- Seamless integration with DITA-OT for multi-format publishing (HTML5, PDF, EPUB, and more).
- Smart navigation, live preview, and 21 code snippets to generate bookmap, ditamap,topic templates.
Whether you’re a technical writer, developer, or student, DitaCraft helps you focus on learning DITA — without the complexity.
(...)
Who Is DitaCraft For?
- Beginners who want to learn DITA without the complexity of professional tools.
- Developers who need a lightweight DITA editor integrated into VS Code.
- Students exploring structured authoring and technical documentation.
- Technical writers who want a free, open-source alternative for quick edits and validation.
The Future of DitaCraft
DitaCraft is an ongoing project, and I welcome contributions from the community! Whether you’re a DITA expert or a beginner, your feedback and ideas can help shape the future of this tool.
Try DitaCraft today and simplify your DITA journey! 🔗 Install DitaCraft from the VS Code Marketplace"
#DITA #DITAXML #XML #VSCode #VisualStudioCode #StructuredWriting #TechnicalWriting #DitaCraft
@stevencudahy #mastoprompt
-Ruin
The shell of past lives,
Echo mourning choughs laments,
Of wrack and ruin,
"The success of any AI initiative in technical communication depends on how responsibly it is applied. The workflows described so far – drafting, revision, and quality assurance – can all deliver real benefits, but only when guided by principles that protect clarity, accuracy, and accountability. Without those guardrails, AI becomes another source of noise rather than a tool for improvement.
The first principle is clarity. AI should never obscure meaning or introduce unnecessary complexity. Writers must always verify that generated or revised content still serves its audience and that explanations remain specific and concrete. A perfectly grammatical sentence that confuses readers is not an improvement.
The second principle is accuracy. AI systems cannot verify facts or interpret technical details with the precision of a subject matter expert. Any information produced or edited by a model must be checked against source materials and validated through established review channels. This step is not optional.
The third principle is accountability. Human writers and editors remain responsible for the content they publish, regardless of how it was created. That responsibility extends to ethical and legal considerations such as data privacy, bias mitigation, and compliance with organizational standards. Every AI-driven workflow should include clear documentation of how the system was used and who approved the results.
The final principle is transparency. Teams should share their AI practices openly within their organizations. This builds trust with stakeholders and prevents misuse born of misunderstanding. When people know what AI is doing and why, they are more likely to support its use.
Responsible adoption is what separates innovation from recklessness. The goal is not to prove that AI can write or edit, but to show that humans can use it wisely."
I just recently noticed that there are not many in-depth resources about SDK documentation for technical writers. I think this presentation provides a good "no frills" overview of the topic:
"SDK docs written by developers tend to be implementer oriented, not user oriented. That makes sense, since it's the implementers writing them. Unfortunately, this approach leads to some frustrating SDK reference manual experiences for users. The implementer-oriented doc writer tends to answer, "What is this built on?" As a user, I need docs that tell me, "What can I build with this?"
I provide examples of common SDK docs pitfalls, then present the approach that I used updating the SDK documentation that our developers had created. My goal was to give users of those docs a quick, enjoyable, user-oriented experience. To do so, I identified the likely use cases, or flows, of our product. I then grouped all entities (classes, functions, etc.) of the docs into these flows. For each flow, I arranged the entities in "flow order".
Having mapped out our codebase in this way, I was ready to begin adding content by following these principles:
1) In the leading lines, answer: what is this for? 2) Always link to the previous and next items in all flows and add "See Also" links. 3) Add a code example that demonstrates this entity's role in the flow. 4) Call out gotchas that are likely to get in the user's way when trying to use a flow."
#TechnicalWriting #SoftwareDocumentation #SDKs #SDKDocumentation
Yep, DITA XML is still rocking in the technical communication world and technical writers need to have at least some familiarity with the topic.
https://learningdita.com/pluginfile.php/1/tool_certificate/issues/1762964073/6088999983MC.pdf
#DITA #DITAXML #TechnicalWriting #TechnicalCommunication #StructuredWriting
"As agentic assistants get more capable, I’m seeing more emphasis on long-running tasks. These are tasks that require less human intervention and give more autonomy to the agents to make decisions along the way to achieve the task’s goal. In some ways, it seems like a primary activity for future tech comm work might involve carefully crafting long-running prompts that allow a technical writer to fully automate a task. The tech writer’s role then becomes focusing on designing prompts, instructions, and skills that highly capable autonomous agents can follow to complete the doc-related tasks. The more complex the task, the more complex the prompt.
However, I think this idea seems appealing in theory only. In reality, long-running tasks have limited application and aren’t representative of 90% of the documentation tasks I do. Most documentation tasks involve iterative decision-making along the way based on feedback loops. Although many people would like tech writers to automate their tasks, the reality is that most doc scenarios are one-offs and not repeatable in a prompt that would apply to future doc tasks.
Based on the need for the human-in-the-loop to steer, provide feedback, course correct, and apply judgment all along the way of a process—in constant conversation with an AI agent acting as a thought partner rather than a wholly autonomous agent—I don’t foresee long-running tasks being all that important for tech comm work."
https://idratherbewriting.com/blog/collaborative-thought-partner-not-autonomous
#TechnicalWriting #SoftwareDocumentation #AI #GenerativeAI #AIAgents #AgenticAI #HumanInTheLoop #LLMs
"Technical writers have survived technological changes for decades. The advent of AI shouldn’t be different. If this reminds you of Realpolitik, you wouldn’t be wrong: LLM-generated contributions are already happening and there’s no going back. Writing an AI & Docs policy means taking full ownership of the process and reminding folks that documentation requires expertise and has high quality standards. That kind of strategic thinking is what will keep us afloat.
What I would find dangerous for technical writing right now is sitting on our hands, hoping that someone else sets the rules of the game. We can’t pretend that this will sort it out on its own, so start drafting your policy, your stance, and iterate as you learn more. Your policy will also act as a reminder of the value you bring to the organization. Worst case scenario, it’ll open useful internal debates that you might have missed otherwise. We need that depth."
https://passo.uno/ai-docs-policy-contributions/
#AI #GenerativeAI #AIPolicy #TechnicalWriting #SoftwareDocumentation #DocsAsTests #LLMs
