Augmenting AxonIQ's Documentation Usability: Enhancing Developer Productivity

Axon Framework
1

Hello AxonIQ Community,

As a regular user of AxonIQ’s tools, I’ve navigated the Axon Reference Guide. From this, I’ve curated a few enhancement suggestions that aim not just at a better user experience but also at fostering developer productivity.

1. Integration of Diataxis Framework & Its Impact on Developer Productivity:

Adopting the Diataxis documentation framework can be a game-changer. This structured approach segments content into:

  • Tutorials: For those new to concepts.
  • How-to guides: Direct solutions to specific problems.
  • Explanation: Delving deeper into the nuances of concepts.
  • Reference: Quick information resources.

Utilizing Diataxis ensures a streamlined documentation approach, dramatically cutting down the time developers spend searching for information. This, in turn, significantly boosts developer productivity.
It’s worth noting that Developer Productivity Engineering is becoming central to modern tech enterprises. According to research like the DORA DevOps Report (https:// dora.dev/research/), enhanced developer productivity directly correlates with improved software delivery performance. This not only means faster development cycles but also higher quality releases. Thus, by refining documentation, we indirectly propel software delivery excellence.

2. “Improve this Documentation” Link:

A collaborative approach always excels. An “Improve this documentation” link on every page could redirect contributors to platforms like GitHub. This harnesses the collective intelligence of the community for documentation refinement.

3. UX Feedback Integration:

Immediate feedback can spotlight areas of improvement. A concise UX survey post each section could offer actionable insights. Queries like “Did this information suffice?”, “How can we elucidate further?”, or “Any improvement areas?” can ensure the documentation evolves based on real user needs.

4. AI-powered Chatbot or Search Mechanism:

Incorporating an AI chatbot or search feature, anchored by a potent language model, could redefine user interaction. Users could instantaneously locate precise information, further amplifying productivity.

Taking these recommendations onboard, AxonIQ’s documentation could stand as a beacon for clarity, efficiency, and developer productivity. Keen to hear feedback from fellow users and AxonIQ’s team. Here’s to creating a documentation resource that’s truly by the community, for the community!

Warm regards,
Tobias

2 Likes
2

Tobias, this is a set of very helpful suggestions you’re given.
As it stands, we are actually working on something that’s called AxonIQ Library, which you can find here.

The intent is to make AxonIQ Library the single point of documentation for all our tools.
Furthermore, we actually aim to:

  1. Introduce the Diatiaxis Documentation Framework, as you can see here on our new library.
  2. Have “Improve this Documentation” links on pages, as you can see here for example. I do need to note we currently have those links for unfinished pages. Adding them to all makes sense to help readers give their suggestions ASAP makes sense, actually.

I think your third and fourth suggestions also make sense, although they deserve a little more discussion on our end I think.
Though I do think those will come later.

Moving the Reference Guide into the Diatiaxis Documentation format is already a lot of work if I am frank. Although the plans are there, the Axon Framework and Axon Server teams have not been able to prioritize it yet.

This is different for our newer tools, though. Axon Synapse is already on the Library, and AxonIQ Console will too, once it is out of beta.

Although I cannot speak for the Server team, I can state that the Framework team aims to use this new format for Axon Framework 5 right away.

1 Like
3

Looks quite amazing so far! Writing good documentation can be quite challenging, so I understand that converting the existing documentation is not an easy task.

2 Likes