📗 Improve structure in documentation about boaviztapi HOT 8 CLOSED

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.

from boaviztapi.

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 ?

from boaviztapi.

+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.

from boaviztapi.

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

from boaviztapi.

First structure update in #53

from boaviztapi.

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

from boaviztapi.

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

from boaviztapi.

@demeringo could we consider this issue resolve ?

from boaviztapi.