New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[UX] New documentation hierarchy suggestion #884
Comments
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 😛) |
Hey @alanpoulain, thanks for your review. +1 for GraphQL, maybe between The Admin Component and Testing ? |
IMHO before The Admin Component would be better since the admin could be compatible with GraphQL as well. |
I'm 👍 to restructure the documentation, and most ideas looks good to me but:
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 😅, but it can definitely be improved. |
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!! |
Regarding the |
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. |
Not using Docker for a professional project is not an option in 2019 IMHO. And users wanting to customize everything can do it, it’s documented (but I don’t think it’s a best practice). Most users should use Docker and it’s what we must promote. |
Yes, but I think, most of the time, users have already their own Docker images and want to use API Platform in existing projects. |
Regarding Docker:
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). |
@alanpoulain Interesting, I didn't think of doing this that way. Is there a public example of this? This kind of tricks would be very welcome in the new How do I? subject :-) |
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
My suggestion:
WDYT? |
Hey there,
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:
The Api Component sublevels are far too many, and don't share the same level of importance (i.e NelmioApiDocBundle being sibling of Operations, for instance)
Starting by the Distribution makes look like Api-Platform can't work without a proper Docker setup and all the things (mercure, h2 push, varnish, let's encrypt, postgresql, ...), which isn't true.
With the advent of Flex, everything is done in Symfony to make applications from simple to advanced: you only
composer req
the components you need.Beside, if we can assume the user has a minimal knowledge of Symfony (it is used under the hood along with Doctrine, share the same concepts, components and structure), Api-Platform can work without Docker, so we shouldn't add Docker into the learning curve if it's not mandatory.
As a consequence, I think the distribution should not be the very starting point, but exposed as a great tool to get a full-featured environment.
The starting point could be a simple
composer req api && bin/console server:start
, to focus on the API itself instead of its environment.In the meantime, example commands should not be prefixed by
docker-compose exec
.Similarly, some components (schema generator, client generator, ...) are useful tools but may not deserve a top-level position in the documentation hierarchy (generators being useful doesn't mean they are necessary). It make them look like they're completely part of Api-Platform and you can't work without them, which is wrong. At least it makes you focus on the stack instead of the core.
They could be grouped in a sub level and/or expanded in a separate documentation.
Some topics cover easy setup as well as advanced coding and configuration. While this might be a good idea at first glance, most of the time it leads to extremely scrollable pages and things the user doesn't want to read at this moment. It also makes the information hard to find when you're looking for something. Hacks and tricks should be moved away in a specific section, in my opinion (and linked from the main topics they're related to).
The documentation sections hierarchy should target newcomers at first, and go to experienced users at the end.
An F.A.Q. or How do I? section is really missing. Having such a section could also lead some developers to share their own recipes and help the community.
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:
API-Platform
Introduction
Installation
Usage and configuration
Pagination, filters and sorting
Security
Exposing your API
Consuming your API
The Admin Component
Testing
Deployment
Caching & performance optimization
Advanced Usage
How do I?
Troubleshooting
A more detailed reorganization is available on this gist.
What do you think?
Sorry for the long post! 😅
The text was updated successfully, but these errors were encountered: