Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
[UX] New documentation hierarchy suggestion #884
API-Platform is an ecosystem full of features and tools, but its documentation is growing fast, and it begins to lack of an appropriate structure to keep things tidy and clear.
I have identified several drawbacks on the current documentation that could lead astray newcomers:
Read -> Install -> Configure -> Play -> Code -> Test -> Deploy -> Tune -> Hack
After thinking about this, I suggest the following key topics to drive the user from basics to advanced:
A more detailed reorganization is available on this gist.
What do you think?
Sorry for the long post!
I think the aim was the contrary: having the distribution to be the common way to use API Platform and the best setup to present the examples.
You're perfectly right about restructuring the documentation. API Platform is growing and the current documentation is messy: I think new developers are quickly lost and maybe some people give up their motivation for using it when they see the documentation.
(and I think GraphQL should have its own topic
Also, there was a bug on the website affecting the order in the menu (the order was totally irrelevant because of this bug). It has been fixed by api-platform/website#148 3 days ago. The order should looks more logical now
I like the new TOC by the way, for the Core component.
I would suggest some changes regarding the it:
And! The "advanced" section is a very very good idea!!
I don't really agree with this part:
You're right when the user wants to try it, in a workshop or to show it, but when someone or a company wants to really use it in their project, they don't need (and don't want) to use the full framework with all this stuff in it. They want to pick what they need and it's often a
Of course, I also think promoting the full ecosystem is a great thing to do, to envision all the possibilities. But we should show it off in the main page and maybe in the first part of the "Getting Started" topic but the advanced documentation should not use it.
Totally agree with @alanpoulain.
Regarding your following comment:
I understand (and share) your point, but it actually sounds confusing. JS tools are part of the stack but they're designed to work as standalones. When invoking the API-Platform name, what comes to your mind? The full-stack framework? The core? The Docker Distribution? A set of standalone components designed to work together? Maybe all this could be clarified, not at the documentation level, but at the website one (with icons, separate menus, etc). Maybe in a second time. Anyway, as they're designed to work as standalone components, I agree they deserve a 1st place in the overall documentation.
Regarding your suggested changes in the core documentation:
Using custom DataProvider/Persister is also very useful when you want to have a resource not linked to Doctrine. Typically when you need to create a "command" endpoint, for sending a mail for instance or when it impacts multiple entities and not just one. @teohhanhui has used this pattern a lot I think for the Sylius Shop API (which is not a CRUD one).
I think @dunglas tries to explain it here: #888.
Another recurrent consistency issue:
Disabling Swagger UI
# api/config/packages/api_platform.yaml api_platform: # ... enable_swagger_ui: false
It will switch your default documentation UI to ReDoc.
Manually Registering the Swagger UI Controller
# app/config/routes.yaml swagger_ui: path: /docs controller: api_platform.swagger.action.ui