Refactor documentation content organization about microcks.io HOT 10 CLOSED

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

from microcks.io.

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

from microcks.io.

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

from microcks.io.

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!

from microcks.io.

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:

from microcks.io.

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! 🏅

from microcks.io.

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!

from microcks.io.

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.

from microcks.io.

🌟 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

from microcks.io.

Now done and published!

from microcks.io.