Closed demeringo closed 2 years ago
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.
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 ?
First structure update in #53
@odelcroi I realize you are also working on the doc, so I add you to the PR and conversation.
+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.
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
@demeringo could we consider this issue resolve ?
@da-ekchajzer, I close it, docs are fine now.
Problem
Current documentation contains interesting topics (tutorials, explanation of methodology, API reference documentation) but the documentation is a bit difficult to navigate.
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:
It could also be interesting:
Alternatives
Additional context or elements