Refactor documentation content organization

[lbroudoux]

The documentation content, a crucial resource for our organization, is currently disorganized and can pose a challenge for new team members to navigate...
As part of a first brainstorming session between core maintainers, we come with the following wrap-up:

😤 Today’s pains

• “Getting started” is too long…
• Guides take a lot of time to write
• Short explanations (“How to install on…”) are published as blog posts
• Don’t have space/room for short how-to’s
• Too few contributions on “How to install on..”, “How to setup…”
• Missing documentation because of questioning
  • Where to put the AI stuff? In Using? Installing? Automating?
  • Where to put the Backstage stuff?
• Configuration references and explanations (Helm values ⇔ application.properties matching)

🎯 Our goals

• Have a place for short publications
• Favor external contributions on task oriented stuff (“How to…”)
• Being able to cover the whole “lifecycle” of a feature:
  • From teasing to using to explaining all the bits and bytes
• Having guidelines for easier writing and allocation of pieces of docs
• Having comprehensive reference on:
  • Container images with their options
  • Configuration properties
  • Commands
  • APIs

💡 Ideas

• We started to review successful other projects documentation to check how they have the doc organized
  • Started reviews on istio.io, keycloak.org, backstage.io
• We started to look at some documentation methodology like Diataxis
• Reviewed some other project's doc that follows Diataxis principles like djangoproject.com or loopback.io
  • Have to say we like those ideas so far 😉
• We started to project some refactoring using this method and will share it very soon.

🤔 Refactoring concerns

• How to adopt a standard organization that makes users happy and the project successful?
• How to avoid broken links?
• How to manage transition if we have to move pages?
• How to connect the help system within Microcks UI?

Please don't feel intimidated, as this task of documentation refactoring can look huge from the outside. We're definitely looking forward to hearing from you!!

This is an ongoing effort as discussed on our Discord server here: https://discord.com/channels/1162356525969449100/1234906549844185139/1234906550787641496

[lbroudoux]

While bootstrapping this effort, we worked on this Google Slides to set the refactoring goals, hold our reviews and craft a proposed target. Feel free to review it and share your comments here: https://docs.google.com/presentation/d/1FURnV84LqIS3VWQOyZ1dWPgF6exKmq02QvB1PfrVx6I/edit?usp=sharing

[yada]

Regarding "How to avoid broken links?", see #75 -> WIP

[lbroudoux]

Hey community!

I've started working on documentation refactoring as I was mentioning it few weeks ago. See this message: ⁠documentation⁠
I want to share some screenshots of the organization options I chose at the moment to get your feedback on this. Please don't feel intimidated, as this task of documentation refactoring can look huge from the outside. We're definitely looking forward to hearing from you!!

First, let me introduce the fact that I've followed the Diataxis framework for this.

As a consequence, the top-level organization is made of 4 different parts:

• Tutorials that are short learning sequences,
• How-to guides, that are tasks and goals-oriented,
• Explanations, that are there to provide deeper understanding,
• References that are dedicated to providing comprehensive information.

We also integrated an Overview part that is there to give the big picture and some prerequisite concepts.

See what is the result in action:

[lbroudoux]

In the Tutorials section, the proposition is to reuse the Getting started stuffs but to make them lighter. We also thought about adding short and laser focused tutorials on the different styles of APIs like this:

Then the How-to Guides are split into different categories depending on your area of concerns: is it installing? using Microcks? administrating it? So we propose following organization:

Here's the content we foresee in each sub-section:

Then we arrived at the Explanations where you'll find content for diving deep into Microcks concepts. For now, we identified those different topics:

And finally, the References will hold comprehensive lists of conventions, notations, configuration options and parameters as well as API definitions.

You can also see in the latest screenshot above that we have re-worked a bit the navigation display so that margins, parent and ancestors indicators look much more consistent and easy to follow.

What do you think? Who you'd like to help with this initiative? Your feedbacks, comments and ideas are gold for us! 🏅

[lbroudoux]

Regarding "How to avoid broken links?", see #75 -> WIP

I'll create a specific branch to track the work and issues related to this Epic. I think the work from #75 has to be integrated as soon as possible in this branch!

[lbroudoux]

Given the above-proposed organization, I've initialized a Google Spreadsheet to analyze existing content, project a target organization and track how we can move from current situation to target. This is the sheet: https://docs.google.com/spreadsheets/d/1mC-Q3QskqCUpmAsXK5lh_twolaYnMTOkmkETxwNO2lI/edit#gid=573622289

Feel free to check it out, send us comments and if you'd like to be involved in refactoring we'd also be able to provide write access to the sheet for easier collaboration.

[lbroudoux]

A preview website for documentation is available here: https://microcks-io.vercel.app/documentation/
Feel free to send us feedback!

[yada]

🌟 Join Us in Keeping Our Website Up-to-Date and Error-Free! 🚀

Dear Community Members,

We're on a mission to maintain our website, microcks.io, in top-notch condition, ensuring that it remains a valuable resource for everyone. To achieve this goal, we need your help!

A daily issue "External Link Check Refactor Doc Report" will be created to report broken links, ex:
#109

How to Contribute?
One PR Per File: For ease of collaboration and review, please create one pull request per corrected file.

Tag Issue Number: Always tag the issue number (#??) in your pull request description to associate it with the relevant issue.

Verify Links: If you encounter rate limit errors for LinkedIn or GitHub profiles, click on the link, verify its accuracy, and update the .lycheeignore file accordingly to prevent future error reporting.

Need and examples?: 👉 https://github.com/yada/how-to-contribute-microcks.io-doc-refactoring

Let's work together to maintain the excellence of our website! Your contributions make a real difference. 🌟

Happy Contributing! 🎉

Warm Regards,
Yacine

[lbroudoux]

A new "What is Microcks?" page has been written here: https://microcks-io.vercel.app/documentation/overview/what-is-microcks/
Please let us know what you think about it!

[lbroudoux]

Now done and published!