📗 Improve structure in documentation

[demeringo]

Problem

Current documentation contains interesting topics (tutorials, explanation of methodology, API reference documentation) but the documentation is a bit difficult to navigate.

• topics are sometime mixed
• lack of use cases (representing end-users goals)
• the how to use section may be a bit too much technical (or wording use tech terms like 'router' ).
• order of topics may not be optimal.
• 🧭 newly on-boarded users may feel lost

Solution

Adapt documentation to use the Diataxis documentation format: https://diataxis.fr/introduction/ This is a structure of documentation that is commonly used in opensource projects.

The tooling remain the same but the structure would be:

• tutorial (quick on-boarding, easy and instant gratification tutorial to show the basics of what API offers)
• How-to-guide (more in detail task focused tutorials)
• explanation (explaining methodology, global functional and tech design, rationale behind the main choices done)
• reference (detailed referenced doc like routes, parameter formats a.s.o).

It could also be interesting:

• to provide some typical use cases / stories linked to a persona.
• use more diagrams, ideally with tools like mermaid or plantUML for tech diagrams.

Alternatives

• executable API documentation (i.e. to allow user to try functionalities). But this is complex (and custom) to put in place or maintain. Not sure it is worth the effort.

Additional context or elements

• The documentation framework https://diataxis.fr/introduction/
• The book The Design of Web APIs by Arnaud Lauret https://apihandyman.io/

[da-ekchajzer]

Thanks for the analysis. I agree with all your comments. What we have is exhaustive, not accessible. The next iteration should focus on users. I guess we could :

1 – rename "FUNCTIONAL" by explanation. I like the fact that there is 0 code nor API request in this section. It's a way to explain our methodology for non developers. 2 – rename "HOW TO" by reference 3 – Create a real "HOW TO" section with real explainable use cases 4 – Today, "TRY IT OUT" is a more condensed documentation than a proper tutorial. We could keep "TRY IT OUT" as an executable steel cheat and create a quick tutorial to fulfill all the goals you have presented.

I would be interested to hear your opinion on those propositions.

[demeringo]

Hi @da-ekchajzer, yes, I fully agree with theses propositions.👍

To be transparent, I am inspired by (and shamelessly stealing from ;) the documentation of Scaphandre.
IMHO Scaph doc is a great mix of being accessible, easy to read and still provides the details (tech or methodology) that we may be looking for. It follow a structure that is close to the one we discussed.

But I also know that great documentation is a kind of never ending task 🤪.

To start implementation, and still keep this conversation going (on this issue), I propose that we open more specific issues (i.e. that describe small doc refactoring), and link them in _this_issue. This would allow to progress and merge incrementally.

Are you ok with this idea ?

[demeringo]

First structure update in #53

[demeringo]

@odelcroi I realize you are also working on the doc, so I add you to the PR and conversation.

[da-ekchajzer]

+1 on the organization you propose. I will work on the HOW TO part and open a specific issue on that topic and review the first enhancements. I will continue the great tutorial part you have begun.

[da-ekchajzer]

I just merged #60, where I completed the tutorial part, with a custom server configuration and an AWS cloud instance tutorial see : https://github.com/Boavizta/Tools-API/tree/main/docs/docs/getting_started It's up on http://hackaton.boavizta.org

[da-ekchajzer]

@demeringo could we consider this issue resolve ?

[demeringo]

@da-ekchajzer, I close it, docs are fine now.