Improving Technical Documentation with Mermaid Diagrams

Mermaid는 마이크로서비스 아키텍처 등 기술 문서를 코드로 작성해 버전 관리와 리뷰가 가능하도록 하는 도구입니다. 시스템 컨텍스트, 시퀀스, ERD, 상태 머신, 배포 토폴로지 등 5가지 주요 다이어그램 유형을 지원하며, 문서와 코드가 함께 유지되어 다이어그램의 노후화를 방지합니다. CI에서 Mermaid 다이어그램 문법 검증도 가능해 문서 품질을 높이고, 개발자들이 설계 변경 시 다이어그램을 함께 업데이트하도록 유도합니다. 복잡한 서비스 흐름부터 시작해 점진적으로 도입하면 신입 개발자 온보딩과 협업에 큰 도움이 됩니다.

https://mdview.io/s/mermaid-diagrams-for-software-developers

#mermaid #technicaldocumentation #diagramascode #devtools #documentation

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

Tested Next.js native deps on riscv64 hardware (Banana Pi F3). Results:

✅ Sharp WASM: Production-ready (604ms resize 1920×1080, zero crashes)
❌ Prisma: Broken (WASM parser bug, no fix)

Hardware testing beats speculation. 2,400+ lines of docs updated with real numbers.

https://www.linkedin.com/pulse/building-nextjs-swc-from-source-risc-v-journey-ring-maze-verachten-enr6e/

#RISCV #NextJS #WebAssembly #NodeJS #EmbeddedSystems #HardwareTesting #EdgeComputing #OpenSource #Prisma #TechnicalDocumentation #devEco

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

https://diataxis.fr

#TechnicalDocumentation

Technical writing is a pain point for so many orgs I've worked for. It's also a very particular skill to write GOOD documentation. I've seen a few businesses turn this into a full time job which can be effective or create a translation issue when you have an engineer work with someone who's more of a writer than a techie. I honestly I think the best case is when the technical persons are trained on writing and put a few hours each week or month into contributing.

#tech #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/

"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