TL;DR: The rsyslog documentation was a mess — and I knew it. It’s now only “partly OK”, but for the first time we have a clear structure, concept, and plan. AI support, combined with my review and technical expertise, is making this transformation possible — and AI is improving at an impressive pace.
(This post was generated with AI support and fully reviewed and revised by me.)
Admitting the Problem
For years, the rsyslog documentation lacked structure. It grew organically, with a mix of legacy content, outdated examples, and unorganized topics.
I knew it was bad and worried that it drove potential users away — but alone, I could never carve out enough time to rewrite everything.
The Breakthrough: TOC Restructuring & AI
The single most important improvement so far has been restructuring the Table of Contents (TOC) into something coherent.
This provides a foundation for all other work. Without a solid TOC, no amount of “fixing” individual pages would make the documentation usable.
AI has been a real team partner in this effort. It delivers an expert technical writer perspective — something I’m not — while I handle the technical depth and accuracy. It’s also becoming better almost by the week, so I expect its role in future documentation sprints to grow even stronger.
Where We Are Today
- TOC overhaul: The new structure is in place and will guide all upcoming work.
- Beginner’s guide rewrite: A first version is live, but still in its infancy and will be expanded with more real-world scenarios and step-by-step guides.
- Mermaid diagrams and visual aids: Currently in proof-of-concept state on a few pages.
- PoC validation of configuration examples: CI checks ensure that examples are syntactically correct.
This is still far from finished. The majority of old content remains and must be revised, converted, or discarded. The difference is that now we have a clear plan and a concept for systematic improvement.
What’s Next?
We are entering a long-term documentation sprint approach — not continuous work, but focused bursts of effort whenever time allows. (As maintainer, I also need to focus on development, releases, and community support.)
Expect:
- Gradual migration of all legacy content into the new structure.
- Expansion of the beginner’s guide into a complete onboarding experience.
- Expanded real-world tutorials (e.g., TLS forwarding, Elasticsearch, Kafka pipelines).
- More automation and CI checks to ensure future documentation stays accurate.
This process will take months to complete — but the hardest part (setting the direction) is done.
Looking Back and Ahead
In 2024 I wrote about AI and documentation with cautious optimism. Back then, AI wasn’t ready to help much. Today, it’s finally useful — especially as a trusted team assistant for drafting content and refining structure.
I still wouldn’t call our docs “good.” But they’re no longer bad — and now, with AI, I’m confident we can make them excellent.