"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

"In the case of tech writing, thinking that you’re creating docs when what you’re doing is dumping words into a file is particularly wrong, because docs have a moral obligation to solve needs.
(...)
Creating a tutorial aimed at beginners without knowing what the beginner thinks is an empty gesture. Consider any such tutorial in the wild: If instead of following the inviting form of a tutorial it had been written like an entry from a dev diary, it would have offered a more sincere experience, one that would have signaled to the reader that this content wasn’t really for them after all. You can deal with the curse of knowledge either by becoming a beginner, or by not pretending you’re talking to one (that’s why someone like John Carmack is honest).

Unfortunately, organizations often don’t care about the quality of their content (performative or not), and while they might have perceived the signs that they need tech writers, they might still ask folks to create documentation to fulfill a goal or satisfy their particular Definition of Done. Sometimes we can’t escape the script that’s being forced onto ourselves, but, while the fake author in Annie’s post has a cruel side in that it’s utterly devoid of empathy, you can choose not to be like it. This is the duty of tech writers: to uphold clarity and defend user comprehension in all situations where tech comms risk becoming faux."

https://passo.uno/documentation-theater-everybody-loses/

#TechnicalWriting #Documentation #SoftwareDocumentation #DocumentationTheater #SoftwareDevelopment #Tutorials