#technicaldocumentation — Public Fediverse posts

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

This article is great in the sense that it describes most of what I'm doing nowadays as a technical writer. I even put different LLMs reviewing each other's drafts, which is a lot of fun. That's why, personally, I can't be so pessimistic as others are currently being. LLMs are just a new technology that you need to incorporate in your workflows. Of course, there are some skills that will probably become atrofied. At the same time, a new set of skills is emerging. If you don't see that. you will be completely left behind. You just need to use these tools by making use of critical thinking.

"After deliberation for a few months, I reached a conclusion about what I wanted to say: the model that’s emerging is a cyborg model of technical writing, a humans + AI combination. This is in contrast to the many articles, which now seem to come at an even faster pace, saying that AI will replace human labor. I realize there’s a lot of opinion on this debate, but my argument for why the humans + AI (cyborgs) model is the winning one, rather than replacement, is because of this observation: almost no tech writers at my work have automated complex processes using AI. And in my own use of AI over the past few years, the model that’s emerged is a close intertwining of machine and human interaction to produce content. I’m talking with AI all day. It’s not doing much on its own without my constant steering, direction, and feedback."

https://idratherbewriting.com/blog/cyborg-model-emerging-talk

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalDocumentation #SoftwareDevelopment #SoftwareDocumentation

@tuparev @Gte @helge

A useful counterpart — the documentation team's guide for style and design.

I’ll try to find time to scan it in and somewhere to post it…

#RetroComputing
#Writing
#TechnicalDocumentation
#NeXT

Give Us One Manual For Normies, Another For Hackers https://hackaday.com/2025/12/02/give-us-one-manual-for-normies-another-for-hackers/ #Technicaldocumentation #documentation #servicemanual #OriginalArt #Featured #Interest #manual #Rants

"Diátaxis is a way of thinking about and doing [technical] documentation."

https://diataxis.fr

#TechnicalDocumentation

"Opening up the docs roadmap is harder to do when software projects are steered by for-profit companies, because it’s part of wider strategic conversation that might occur behind closed doors, but it’s not impossible. If your documentation is already open source, as well as issues and epics, you can decide to host biweekly or monthly open calls with internal and external docs contributors to get their feedback and ideas, which is an interesting communal complement to UX research.

To reach this level of community contribution requires you to gradually relinquish control. Your role shifts from gatekeeper to orchestrator, from sole author to chief editor of a collaborative narrative. This is where documentation transcends mere utility and becomes something closer to folklore: a living, breathing testament to how real people engage with your creation."

https://passo.uno/docs-contribution-journey/

#TechnicalWriting #TechnicalDocumentation #DocsAsCode #SoftwareDocumentation #OpenSource #FLOSS #SoftwareDevelopment

It's not very often that GPT5 surprises me. In fact, I would say it's quite rare when compared to Gemini 2.5 Pro. But this time, it really, really surprised.

I asked the LLM if it could provide me a list of tools, technologies, and platforms used for documenting software, ordered from a less "docs-as-code" approach to a more documentation-based approach were docs are seen as product. I also noted that this list should also represent the level of technological autonomy provided by each tool - from less to more autonomous.

The output left me really astonished, in the sense that's perfectly accurate and spot on:

#TechnicalWriting #DocsAsCode #TechnicalDocumentation #SoftwareDocumentation #SoftwareDevelopment #TechnicalCommunication

Wednesday, July 16, 2025

Mass attack hits cities overnight as Ukrainians brace for 50 more days of Russian terror — Ukrainian startup says its drones could work on their own by year’s end, thanks to AI — Russian agent caught ‘red-handed’ planting explosives in Rivne apartment building — 5 killed, 53 injured in Ukraine as Russia strikes hospitals, residential areas across country … and more

https://activitypub.writeworks.uk/2025/07/wednesday-july-16-2025/

Wednesday, July 16, 2025

Mass attack hits cities overnight as Ukrainians brace for 50 more days of Russian terror — Ukrainian startup says its drones could work on their own by year’s end, thanks to AI — Russian agent caught ‘red-handed’ planting explosives in Rivne apartment building — 5 killed, 53 injured in Ukraine as Russia strikes hospitals, residential areas across country … and more

https://activitypub.writeworks.uk/2025/07/wednesday-july-16-2025/

Wednesday, July 16, 2025

Mass attack hits cities overnight as Ukrainians brace for 50 more days of Russian terror — Ukrainian startup says its drones could work on their own by year’s end, thanks to AI — Russian agent caught ‘red-handed’ planting explosives in Rivne apartment building — 5 killed, 53 injured in Ukraine as Russia strikes hospitals, residential areas across country … and more

https://activitypub.writeworks.uk/2025/07/wednesday-july-16-2025/

Wednesday, July 16, 2025

Mass attack hits cities overnight as Ukrainians brace for 50 more days of Russian terror — Ukrainian startup says its drones could work on their own by year’s end, thanks to AI — Russian agent caught ‘red-handed’ planting explosives in Rivne apartment building — 5 killed, 53 injured in Ukraine as Russia strikes hospitals, residential areas across country … and more

https://activitypub.writeworks.uk/2025/07/wednesday-july-16-2025/

Wednesday, July 16, 2025

Mass attack hits cities overnight as Ukrainians brace for 50 more days of Russian terror — Ukrainian startup says its drones could work on their own by year’s end, thanks to AI — Russian agent caught ‘red-handed’ planting explosives in Rivne apartment building — 5 killed, 53 injured in Ukraine as Russia strikes hospitals, residential areas across country … and more

https://activitypub.writeworks.uk/2025/07/wednesday-july-16-2025/

"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."

https://passo.uno/whats-wrong-ai-generated-docs/

#AI #GenerativeAI #LLMs #Chatbots #TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #SoftwareDevelopment #TechnicalDocumentation #Docs

"[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."

#AI #GenerativeAI #Writing #TechnicalWriting #SoftwareDocumentation #TechnicalDocumentation #TechnicalCommunication

https://idratherbewriting.com/blog/jonathan-warner-more-than-words-book-review

#TechnicalWriting #Markdown #SoftwareDocumentation #ContentStrategy #TechnicalDocumentation: "So what happens is that Markdown allows you to be the ninja content strategist: you entered the organization, you are not asking folks to learn anything different than what they know. And then you start building on it.

You have to realize that this is a Trojan horse strategy. Like, you want the docs to be the product, fine. This is what all tech writers want eventually. But be very careful about the product not being, for example, the pipelines or the site you’re gonna render. I mean, that might be part of the product. The product is the docs, right? But you have to enter a software company with Markdown with that mindset. Otherwise it will just turn into something that’s not even a feature, and lose importance.

The value of Markdown is that it allow us to enter with very low friction into worlds that maybe haven’t even thought about docs.”" https://passo.uno/pros-cons-markdown/

I'm really glad I documented my own setup process for my firewalls. It has been so long since I had to set one up new out of the box that I wouldn't be able to do this without it! #technicaldocumentation

@minego #SoftwareDevelopment #technicalDocumentation

In July 15, #Akademy, the annual #KDE conference, will take place in Thessaloniki, Greece.

I'll be presenting the remote talk "Documentation Goals and Techniques for KDE and Open Source" at 13:25 UTC (or 10:25 GMT-3 for the Brazilian folks, or 16:25 for attendants in Greece).

This #Akademy2023 talk will be my first, although I've attended the event remotely before.

I'll be talking about #Documentation, its dos and don'ts, and the things I've read in technical documentation books and articles and how they apply to #OpenSource.

I'll also be talking about the four main areas of documentation in KDE, and how you can start contributing to it.

Lastly, I'll show you a few resources you can use to learn more about #TechnicalDocumentation.

You can register for the event here.

All talks will be mainly transmitted on Matrix, and relayed to PeerTube and YouTube.

See you there! 🐰

I’m going to be spending the next two weeks of my life writing #TechnicalDocumentation and summaries for a project I’ve been working on since April.

The adult in me likes the structure documentation brings and working towards the conclusion of a satisfying project.

The kid in me is screaming that I’d rather be outdoors or eating a bowl of frosted mini-wheats.

(Digital) #whiteboarding can help grow an idea. But don't mistake it for #TechnicalDocumentation, the real foundation of a durable product. No one will look at that #Miro board once the meeting is over!

"People use Post-its to […] make meetings more collaborative […] Instead, images of such sessions became products themselves. […] Their meaning doesn’t come from what is written, but from its having been written across colorful rectangles and squares."

#designthinking

https://www.wired.com/story/beware-the-digital-whiteboard/

#AI #ML #Ethics #Law #CompSci #TechnicalDocumentation: "The growing need for accountability of the people behind AI systems can be addressed by leveraging processes in three fields of study: ethics, law, and computer science. While these fields are often considered in isolation, they rely on complementary notions in their interpretation and implementation. In this work, we detail this interdependence and motivate the necessary role of collaborative governance tools in shaping a positive evolution of AI. We first contrast notions of compliance in the ethical, legal, and technical fields; we outline both their differences and where they complement each other, with a particular focus on the roles of ethical charters, licenses, and technical documentation in these interactions. We then focus on the role of values in articulating the synergies between the fields and outline specific mechanisms of interaction between them in practice. We identify how these mechanisms have played out in several open governance fora: an open collaborative workshop, a responsible licensing initiative, and a proposed regulatory framework. By leveraging complementary notions of compliance in these three domains, we can create a more comprehensive framework for governing AI systems that jointly takes into account their technical capabilities, their impact on society, and how technical specifications can inform relevant regulations. Our analysis thus underlines the necessity of joint consideration of the ethical, legal, and technical in AI ethics frameworks to be used on a larger scale to govern AI systems and how the thinking in each of these areas can inform the others."

https://arxiv.org/abs/2305.18615

@cisacyber #RedTeam Shares Key Findings to Improve #Monitoring and #Hardening of #Networks - a recommended read for anyone managing a network cyber security team :WeAreNameless:

https://www.cisa.gov/news-events/cybersecurity-advisories/aa23-059a

#TechnicalDocumentation #IOCs #TTPs #CyberDefense #CyberWar #CISA

summarized here: https://www.eke.li/2023/02/domains-in-docs/

when writing #technicalDocumentation - don't use real #urls or #ipAddresses. you never know what will grab those and use them.

there are reserved #domains and #ipRanges for just this!

for #url: the top-level-domains
.test, .example, .invalid and .localhost and the domain example.com are reserved

for ip-adresses the blocks 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24 are reserved

they are always safe to use in #documentation

Priority of Knowledge Transfer =

Importance of Knowledge + Availability of Knowledge + Frequency of Knowledge

#KnowledgeTransfer #Documentation #Docs #WriteTheDocs #TechnicalDocumentation

Let’s Make SCPI More Helpful - The SCPI (Standards Command for Programmable Instruments) protocol is exceptionall... - https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/ #self-documentinginterface #technicaldocumentation #softwarehacks #toolhacks #libscpi #scpi

Let’s Make SCPI More Helpful - The SCPI (Standards Command for Programmable Instruments) protocol is exceptionall... - https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/ #self-documentinginterface #technicaldocumentation #softwarehacks #toolhacks #libscpi #scpi

Let’s Make SCPI More Helpful - The SCPI (Standards Command for Programmable Instruments) protocol is exceptionall... - https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/ #self-documentinginterface #technicaldocumentation #softwarehacks #toolhacks #libscpi #scpi

Let’s Make SCPI More Helpful - The SCPI (Standards Command for Programmable Instruments) protocol is exceptionall... - https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/ #self-documentinginterface #technicaldocumentation #softwarehacks #toolhacks #libscpi #scpi

Let’s Make SCPI More Helpful - The SCPI (Standards Command for Programmable Instruments) protocol is exceptionall... - https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/ #self-documentinginterface #technicaldocumentation #softwarehacks #toolhacks #libscpi #scpi

Let’s Make SCPI More Helpful

https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/

#self-documentinginterface #Technicaldocumentation #SoftwareHacks #ToolHacks #libscpi #scpi

Let’s Make SCPI More Helpful

https://hackaday.com/2023/02/02/lets-make-scpi-more-helpful/

#self-documentinginterface #Technicaldocumentation #SoftwareHacks #ToolHacks #libscpi #scpi

https://httpwg.org/ is a neat website for reading HTTP specifications. It uses a nice easy on the eyes reading font, has an index with links in between sections and *colors* 🎨

Does anyone know of any other website that acts a modern rfc-editor.org for RFCs? #http #rfc #documentation #tech #technicaldocumentation #readinghelps

As long as the #Documentation isn't sufficiently detailed, folks are going to have a hard time taking #Mastodon seriously.

But docs are not a two-person effort. It's not just up to Eugen to make them better. If you are a #TechnicalWriter and you're not afraid of a little #GitHub , contribute, especially when you see that something is unclear!

Mastodon is so far a labor of love. Let's help keep it growing.

#OpenSource #Contributing #Volunteer #TechnicalWriting #TechnicalDocumentation

I'm obsessed with good #documentation and the Routinator user manual on #ReadTheDocs is my pride and joy.

We worked very hard to seamlessly integrate the manual page into it as well, allowing us to automatically link command line options, but we also wanted it to be the canonical source for building the the manpage with rst2man. This saves us from keeping content in sync and messing with troff(1).

https://github.com/NLnetLabs/routinator/blob/main/doc/manual/source/manual-page.rst

#WriteTheDocs #TechnicalWriting #TechnicalDocumentation #OpenSource

Shameless brag: yesterday I submitted two pull requests for changes to #Mastodon #Documentation, and @Gargron kindly approved and merged!

The changes clarify what you need to do to change #Post #Privacy at the default or per-post level. You can see the updates at the links below.

#TechnicalDocumentation #OnlineHelp #TechnicalWriting #OpenSource #Development #Contributing

https://docs.joinmastodon.org/user/posting/#privacy

https://docs.joinmastodon.org/user/preferences/#posting

Making Web Pages with Word? - If you’ve ever examined the messy HTML that results from doing a Save As HTML from... - https://hackaday.com/2021/09/02/making-web-pages-with-word/ #technicaldocumentation #htmlconversion #microsoftword #techhacks #webpages #html