#SoftwareDocumentation

Miguel Afonso Caetano“When I say that tech writers should own the prompt that generates documentation, I mean two things: that they should design and maintain the prompts, and that they should spearhead docs automation initiatives themselves, as I suggested in my tech writing predictions for 2025. It’s not just about using LLMs at work or tolerating their existence: writers must lead the way and own the conversations with AIs around docs.What Aikidocs aims at showing is that you can work with an LLM as you would with a tech savvy intern: you provide a style guide, concrete guidance, and source materials to get acceptable output on the other side of the black box. All the content created in those carefully fenced pens will follow your content strategy more than if you let opinionated tools do it for you.It’s not vibe coding: it’s LLM surfing.”<a href="https://passo.uno/build-tech-writing-tools-llms/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://passo.uno/build-tech-writing-tools-llms/</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#LLMs</a>

QUnitEver wondered how beforeEach works in unit test frameworks? Check out our new lifecycle diagram!<a href="https://qunitjs.com/lifecycle/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://qunitjs.com/lifecycle/</a>People generally guess right when it comes to ordering, so why a diagram?We want to show that the order is guaranteed, and showcase what's possible when you depend on it.Thanks to FND, Jan, and NullVoxPopuli for improving and promoting this work! H/T <a href="https://hachyderm.io/@FND" class="u-url mention" rel="nofollow noopener noreferrer" target="_blank">@FND</a> <a href="https://hci.social/@simulo" class="u-url mention" rel="nofollow noopener noreferrer" target="_blank">@simulo</a> <a href="https://mastodon.coffee/@nullvoxpopuli" class="u-url mention" rel="nofollow noopener noreferrer" target="_blank">@nullvoxpopuli</a> <a href="https://fosstodon.org/tags/qunit" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#qunit</a> <a href="https://fosstodon.org/tags/WriteTheDocs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#WriteTheDocs</a> <a href="https://fosstodon.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://fosstodon.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://fosstodon.org/tags/documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#documentation</a> <a href="https://fosstodon.org/tags/TDD" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TDD</a>

Miguel Afonso Caetano"Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.This post explains terminology and concepts, to help you get a mental model of what's going on. If you prefer to dive in and pick up concepts as you go, skip straight to the tips in How to learn, and come back to the conceptual info as needed."<a href="https://deborahwrites.com/blog/docs-like-code-basic-intro/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://deborahwrites.com/blog/docs-like-code-basic-intro/</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Programming</a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#DocsAsCode</a> <a href="https://tldr.nettime.org/tags/Git" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Git</a> <a href="https://tldr.nettime.org/tags/Markdown" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Markdown</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://tldr.nettime.org/tags/MkDocs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#MkDocs</a> <a href="https://tldr.nettime.org/tags/VSCode" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#VSCode</a>

Miguel Afonso Caetano"When evaluating documentation’s role, consider these broader strategic questions:- Strategic positioning: How does documentation support the company’s core strategic approach?- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?- Value proposition: How does documentation contribute to the product’s overall value for customers?- Knowledge management: How does documentation support internal knowledge retention and transfer?- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"<a href="https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Documentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a>

Miguel Afonso Caetano"You can replace tech writers with an LLM, perhaps supervised by engineers, and watch the world burn. Nothing prevents you from doing that. All the temporary gains in efficiency and speed would bring something far worse on their back: the loss of the understanding that turns knowledge into a conversation. Tech writers are interpreters who understand the tech and the humans trying to use it. They’re accountable for their work in ways that machines can’t be.The future of technical documentation isn’t replacing humans with AI but giving human writers AI-powered tools that augment their capabilities. Let LLMs deal with the tedious work at the margins and keep the humans where they matter most: at the helm of strategy, tending to the architecture, bringing the empathy that turns information into understanding. In the end, docs aren’t just about facts: they’re about trust. And trust is still something only humans can build."<a href="https://passo.uno/whats-wrong-ai-generated-docs/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://passo.uno/whats-wrong-ai-generated-docs/</a><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#LLMs</a> <a href="https://tldr.nettime.org/tags/Chatbots" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Chatbots</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/TechnicalDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalDocumentation</a> <a href="https://tldr.nettime.org/tags/Docs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Docs</a>

Miguel Afonso Caetano"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.What are you documenting?When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."<a href="https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Documentation</a> <a href="https://tldr.nettime.org/tags/DocsAsCode" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#DocsAsCode</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://tldr.nettime.org/tags/InformationArchitecture" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#InformationArchitecture</a> <a href="https://tldr.nettime.org/tags/CCMS" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#CCMS</a>

Miguel Afonso Caetano"[E]ven thinking about the right approach for documentation, apart from the documentation artifact I end up producing, is a form of thinking. And this is my larger point, more than the specific logic of my actual argument. Deciding on the approach is a form of thinking that technical writers engage in. Even when we use AI tools to streamline documentation, it doesn’t mean we’re removing ourselves from thinking and reflection. As long as we’re still engaging somewhere, I think Warner would approve. In this way, we use AI tools to augment and amplify the scope of our thinking, not reduce it."<a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/Writing" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Writing</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/TechnicalDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalDocumentation</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://idratherbewriting.com/blog/jonathan-warner-more-than-words-book-review" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://idratherbewriting.com/blog/jonathan-warner-more-than-words-book-review</a>

Miguel Afonso CaetanoHire more technical writers: Isn't the solution obvious?? :-D"Documentation was especially valuable when it came time to refactor code by providing a blueprint that saved time and improved focus. The researchers found that good documentation “ensures that refactoring efforts are directed towards tangible and specific quality improvements, maximizing the value of each refactoring action and ensuring the long-term maintainability and evolution of the software.”As our co-founder Joel Spolsky put it, documentation encodes generational wisdom that goes beyond the simple specs of what was built. “Think of the code in your organization like plumbing in a building. If you hire a new superintendent to manage your property, they will know how plumbing works, but they won’t know exactly how YOUR plumbing works,” said Spolsky. “Maybe they used a different kind of pump at their old site. They might understand how the pipes connect, but they won’t know you have to kick the boiler twice on Thursday to prevent a leak from springing over the weekend.”If we know from decades of research that documentation is a key component of creating and maintaining quality code, why is it so often considered low-priority work developers would rather avoid if they can be writing code instead? (...) By embracing AI-powered documentation tools, development teams can significantly reduce toil work, mitigate technical debt, and foster an environment where developers can thrive. Wise organizations will also keep humans in the loop, ensuring that documentation engineers or technical writers act as editors and stewards of any AI-generated documentation, preventing errors or hallucinations from creeping into otherwise accurate docs."<a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Documentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Programming</a> <a href="https://stackoverflow.blog/2024/12/19/developers-hate-documentation-ai-generated-toil-work/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://stackoverflow.blog/2024/12/19/developers-hate-documentation-ai-generated-toil-work/</a>

Miguel Afonso Caetano"[T]he lack of a clear entry path makes the profession less accessible, contributing to a lack of diversity in tech writing teams. If technical writing is to remain relevant in an industry that values innovation and inclusion, it needs to welcome new voices.Fixing this problem won’t happen overnight, but there are steps companies and the broader industry can take to rebuild the pipeline for entry-level talent:- Reintroduce mentorship programs. - Companies can pair senior writers with juniors to share knowledge and help newcomers build confidence. - Redefine “entry-level” roles. - Stop asking for years of experience in entry-level job postings. - Focus instead on transferable skills like writing, research, and adaptability. - Create apprenticeships or internships. - Paid opportunities to learn on the job can give aspiring writers the experience they need to land full-time roles. Invest in training. - Documentation teams should have budgets for upskilling new hires — not just hiring pre-trained professionals."<a href="https://willkelly.medium.com/how-the-technical-writing-profession-betrayed-entry-level-tech-writers-8a0c05617efd" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://willkelly.medium.com/how-the-technical-writing-profession-betrayed-entry-level-tech-writers-8a0c05617efd</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/Docs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Docs</a> <a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Documentation</a>

Miguel Afonso Caetano"Tech comms can be a business, but thinking is not selling: it requires intellectual freedom and courage. Leaving these conversations to engineers risks turning technical communication into a caricature of itself, a four-quadrant fantasy devised to lure developers into thinking that documentation is a simple pastime, yet another Jira task.Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.”<a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/CriticalThinking" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#CriticalThinking</a> <a href="https://passo.uno/tech-writing-depth-issue/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://passo.uno/tech-writing-depth-issue/</a>

Miguel Afonso Caetano"Technical documentation as an industry is at a crossroads. If we don't invest in the next generation of experts—consultants, educators, and documentation strategists—we're looking at a future where companies try to automate away problems they don't fully understand, and the only available documentation training is a two-hour webinar hosted by someone who just discovered Markdown last week.So, if you're an industry veteran, here's my plea: write it all down before you retire. Mentor someone. Record a video explaining why metadata matters. Start a blog. Write a book (or three). Please do something to ensure that when you finally sign off for good, the rest aren't left googling "How to create a sustainable documentation strategy " and getting a bunch of AI-generated nonsense in return.Otherwise, the future of tech comm might be one long, desperate, less-than-helpful Slack thread."<a href="https://www.thecontentwrangler.com/p/the-great-documentation-brain-drain?r=8sej&utm_campaign=post&utm_medium=web" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://www.thecontentwrangler.com/p/the-great-documentation-brain-drain?r=8sej&utm_campaign=post&utm_medium=web</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/Programming" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Programming</a> <a href="https://tldr.nettime.org/tags/BrainDrain" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#BrainDrain</a>

Miguel Afonso Caetano"[W]ith AI-assisted writing, editing, and translation, your proficiency in a specific human language will matter less than your ability in building effective technical communication solutions. It was already like this, but the fact that the code editor I use at work, Cursor, can complete impeccably idiomatic sentences just by hitting the Tab key means that I don’t need to be Hemingway.In technical documentation, language is a circumstance, an implementation detail. We use English because it’s the lingua franca of technology at the moment, and because most software is being produced, or innovated, in the Anglosphere. For all I know, the main language of tech comms could be Chinese, Hindi, or Indonesian in 2049. The democratization of English through LLMs and AI agents will only facilitate this sort of lateral movement.The next tech revolution might come from Bangalore, Shenzhen, or São Paulo. The companies best positioned to understand, document, and build upon these innovations will be those with diverse technical writers who can bridge linguistic and cultural divides. In a world where LLMs handle the mechanical aspects of language production, the truly valuable skills become cross-cultural communication and technical comprehension."<a href="https://passo.uno/native-english-tech-writing/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://passo.uno/native-english-tech-writing/</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/Language" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Language</a> <a href="https://tldr.nettime.org/tags/Communication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Communication</a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#LLMs</a> <a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/English" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#English</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a>

Miguel Afonso Caetano“Fortunately, I think there’s a good alternative to the dismal picture of brain-dead tech writers pressing buttons on AI machines and passing the content to SMEs for review. That alternative is to focus on what AI algorithms can’t do (at least not with a few button clicks). In this revised approach, tech writers offload the simple tasks to AI tools to fix while focusing their real time and energy on more complex, ambitious tasks that are beyond the straightforward capabilities of AI tools.When I say beyond AI capabilities, I still mean AI tools might assist or augment tech writers in the work; it’s just that the tasks aren’t as simple as the mechanical tasks of fixing doc bugs that I described earlier (e.g., “what’s the issue? what’s the fix?”).For example, when I set about creating complex tree diagrams showing all elements in an API, this was a new kind of documentation that hadn’t been done before at my company. It became an instant hit and one that proved challenging to maintain and grow and fix, but still worthwhile. (In fact, in a chat with a product manager last week, he wondered if our tree diagram page wasn’t the most popular page in our documentation.)If we focused more on these sophisticated tasks (beyond click-button AI), I think tech writers could have a brighter future.”<a href="https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://idratherbewriting.com/blog/recursive-self-improvement-complex-tasks</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#APIDocumentation</a> <a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#LLMs</a> <a href="https://tldr.nettime.org/tags/Docs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Docs</a>

InfoQ📁 <a href="https://techhub.social/tags/FromTheArchive" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#FromTheArchive</a>Crafting <a href="https://techhub.social/tags/ArchitecturalDiagrams" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#ArchitecturalDiagrams</a> isn’t always straightforward. Even simple diagrams can become tricky or prone to errors if not done thoughtfully.Consistent and meaningful diagrams are essential for bringing clarity and fostering consensus among diverse stakeholders.Check out this <a href="https://techhub.social/tags/InfoQ" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#InfoQ</a> article for tips on designing diagrams: <a href="https://bit.ly/40R6YMe" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://bit.ly/40R6YMe</a> <a href="https://techhub.social/tags/SoftwareArchitecture" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareArchitecture</a> <a href="https://techhub.social/tags/SoftwareDesign" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDesign</a> <a href="https://techhub.social/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a>

Miguel Afonso Caetano"In The AI-Driven Leader: Harnessing AI to Make Faster, Smarter Decisions, Geoff Woods makes a point that resonates with me. Woods dismisses people who champion AI as a tool to quickly craft an email or perform other simplistic uses. That sort of task doesn’t move the needle. Using ChatGPT to draft a coherent email might save you 30 seconds here and there, but it’s not something that will help you develop a business strategy as a corporate leader.Woods instead encourages readers to use AI as a “thought partner.” Use your AI thought partner to do tasks like these:- Surface counterpoints to your ideas - Challenge your assumptions - Push your thinking in different directions - Function as a sounding board - Simulate potential scenarios - Role play other points of view - List arguments or considerations for decisions - Analyze data and trends, and moreOverall, engage with AI as a thought partner to think more strategically. Don’t use AI for mechanical tasks alone.When people consider prompt engineering techniques for docs, they too often gravitate toward push-button tasks—simplify this paragraph, format this content, or align it with our style guide. This short sells the power of AI.It’s like having a legendary book editor, perhaps from a prominent New York publishing house, sitting next to you, and you ask them to perform trivial tasks on your content, such as shortening a paragraph here and there. No, you want this person to examine your book’s argument and analyze whether you’ve provided compelling logic. You want them to give insight into alternative approaches and how to incorporate storytelling elements. Don’t make AI just play the role of a copyeditor intern."<a href="https://idratherbewriting.com/blog/ai-eroding-slow-mode" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://idratherbewriting.com/blog/ai-eroding-slow-mode</a> <a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/Writing" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Writing</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://idratherbewriting.com/blog/ai-eroding-slow-mode" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://idratherbewriting.com/blog/ai-eroding-slow-mode</a>

QUnitI'm drafting a diagram to explain how before/after hooks work in unit tests.They tend to work the same way across test frameworks, so it's not unique to QUnit. But, new devs will learn this for the first time, so I think it's worth explaining.Page: <a href="https://qunitjs.com/api/QUnit/module/#hooks" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://qunitjs.com/api/QUnit/module/#hooks</a>Issue tracker: <a href="https://github.com/qunitjs/qunit/issues/1358#issuecomment-2614663327" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://github.com/qunitjs/qunit/issues/1358#issuecomment-2614663327</a>What do you think?<a href="https://fosstodon.org/tags/qunit" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#qunit</a> <a href="https://fosstodon.org/tags/WriteTheDocs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#WriteTheDocs</a> <a href="https://fosstodon.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://fosstodon.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://fosstodon.org/tags/documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#documentation</a> <a href="https://fosstodon.org/tags/devex" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#devex</a>

Miguel Afonso Caetano"As readers of your docs, LLMs have special needs. They don’t see things the same way as humans do (or not yet), nor they care about layout and typography. Their short-term memory is limited and they have serious problems with seeing the big picture. The best way to provide content to LLMs is to think about accessibility options, such as exposing metadata and labeling things carefully. (...) The emergence of LLMs as content consumers doesn’t fundamentally change our mission as technical writers. Just as we learned from the SEO era, our focus must remain on writing clear, high-quality content for humans. What changes is how we deliver this content: LLMs represent a new channel with specific accessibility needs, much like mobile users or screen readers.By implementing proper semantic structure and metadata – the kind of facilitators that made SEO worthwhile – we can serve both human and AI readers without compromising our documentation’s primary purpose. The key, as always, isn’t to write differently, but to package thoughtfully."<a href="https://passo.uno/writing-for-llms-ai-chatbots/" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://passo.uno/writing-for-llms-ai-chatbots/</a><a href="https://tldr.nettime.org/tags/AI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#AI</a> <a href="https://tldr.nettime.org/tags/GenerativeAI" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GenerativeAI</a> <a href="https://tldr.nettime.org/tags/LLMs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#LLMs</a> <a href="https://tldr.nettime.org/tags/Writing" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Writing</a> <a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SEO" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SEO</a> <a href="https://tldr.nettime.org/tags/Metadata" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Metadata</a> <a href="https://tldr.nettime.org/tags/DocsAsData" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#DocsAsData</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a>

Miguel Afonso Caetano"A quick start guide offers concise step-by-step instructions to help users quickly get started with a product, service, or tool. In the context of API documentation, a quick start guide covers the minimal steps required for developers to make their first API call successfully. It typically provides steps such as how to create an account, where to locate API keys or credentials, how to authenticate, example code to make a basic API call, a way to display the response, and troubleshooting tips. The goal is to deliver a quick win to developers and provide a foundation to integrate with your API."<a href="https://www.apimatic.io/blog/how-to-design-a-quick-start-guide-for-your-api" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://www.apimatic.io/blog/how-to-design-a-quick-start-guide-for-your-api</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/APIs" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#APIs</a> <a href="https://tldr.nettime.org/tags/APIDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#APIDocumentation</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/GettingStarted" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#GettingStarted</a> <a href="https://tldr.nettime.org/tags/Tutorials" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Tutorials</a> <a href="https://tldr.nettime.org/tags/SoftwareDevelopment" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDevelopment</a> <a href="https://tldr.nettime.org/tags/DE" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#DE</a> <a href="https://tldr.nettime.org/tags/DeveloperExperience" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#DeveloperExperience</a>

Miguel Afonso Caetano“Don’t cover all the details of the product and the technologies it relies on because no one reads the documentation anyway, right?”WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack. A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way. The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core. <a href="https://books.google.pt/books?id=f7M1DwAAQBAJ" rel="nofollow noopener noreferrer" translate="no" target="_blank">https://books.google.pt/books?id=f7M1DwAAQBAJ</a><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalWriting</a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#SoftwareDocumentation</a> <a href="https://tldr.nettime.org/tags/Documentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#Documentation</a> <a href="https://tldr.nettime.org/tags/TechnicalCommunication" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#TechnicalCommunication</a>

Recent searches

Search options

Administered by:

Server stats: