payload: {"action":"created","issue":{"url":"https://api.github.com/repos/api-platform/docs/issues/884","repository_url":"https://api.github.com/repos/api-platform/docs","labels_url":"https://api.github.com/repos/api-platform/docs/issues/884/labels{/name}","comments_url":"https://api.github.com/repos/api-platform/docs/issues/884/comments","events_url":"https://api.github.com/repos/api-platform/docs/issues/884/events","html_url":"https://github.com/api-platform/docs/issues/884","id":497662919,"node_id":"MDU6SXNzdWU0OTc2NjI5MTk=","number":884,"title":"[UX] New documentation hierarchy suggestion","user":{"login":"bpolaszek","id":5569077,"node_id":"MDQ6VXNlcjU1NjkwNzc=","avatar_url":"https://avatars0.githubusercontent.com/u/5569077?v=4","gravatar_id":"","url":"https://api.github.com/users/bpolaszek","html_url":"https://github.com/bpolaszek","followers_url":"https://api.github.com/users/bpolaszek/followers","following_url":"https://api.github.com/users/bpolaszek/following{/other_user}","gists_url":"https://api.github.com/users/bpolaszek/gists{/gist_id}","starred_url":"https://api.github.com/users/bpolaszek/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bpolaszek/subscriptions","organizations_url":"https://api.github.com/users/bpolaszek/orgs","repos_url":"https://api.github.com/users/bpolaszek/repos","events_url":"https://api.github.com/users/bpolaszek/events{/privacy}","received_events_url":"https://api.github.com/users/bpolaszek/received_events","type":"User","site_admin":false},"labels":[{"id":1081312005,"node_id":"MDU6TGFiZWwxMDgxMzEyMDA1","url":"https://api.github.com/repos/api-platform/docs/labels/Hacktoberfest","name":"Hacktoberfest","color":"d93f0b","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":8,"created_at":"2019-09-24T12:40:44Z","updated_at":"2019-09-27T08:45:35Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"Hey there,\r\n\r\n_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.\r\n\r\nI have identified several drawbacks on the current documentation that could lead astray newcomers:\r\n\r\n* _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)\r\n\r\n\r\n* 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. \r\nWith the advent of _Flex_, everything is done in Symfony to make applications _from simple to advanced_: you only `composer req` the components you need.\r\nBeside, 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.\r\nAs 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. \r\nThe starting point could be a simple `composer req api && bin/console server:start`, to focus on the API itself instead of its environment.\r\nIn the meantime, example commands should not be prefixed by `docker-compose exec`.\r\n\r\n\r\n* 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.\r\nThey could be grouped in a sub level and/or expanded in a separate documentation.\r\n\r\n* 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).\r\n\r\n* The documentation sections hierarchy should target newcomers _at first_, and go to experienced users _at the end_.\r\n\r\n* 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.\r\n\r\n\r\n------------------\r\n\r\n#### Read -> Install -> Configure -> Play -> Code -> Test -> Deploy -> Tune -> Hack\r\n\r\nAfter thinking about this, I suggest the following key topics to drive the user from _basics_ to _advanced_:\r\n\r\n### API-Platform\r\n\r\n1. Introduction\r\n    > State of the art, philosophy, features\r\n\r\n2. Installation\r\n    > On an existing project / new project / docker distribution\r\n\r\n3. Usage and configuration\r\n    > Schema generator, entity map, serialization, events, ...\r\n\r\n4. Pagination, filters and sorting\r\n    > You can start to play with your data\r\n\r\n5. Security\r\n    > JWT, FOSUserBundle, ACLs\r\n\r\n6. Exposing your API\r\n    > Versioning, deprecations, sunset, error messages, ...\r\n\r\n7. Consuming your API\r\n    > OpenAPI/Swagger export, GraphQL support, Client generators\r\n\r\n8. The Admin Component\r\n    > Big topic that should be kept handled apart\r\n\r\n9. Testing\r\n    > Fixtures, writing functional tests\r\n\r\n10. Deployment\r\n    > Kubernetes, Heroku, Platform.sh, ...\r\n\r\n11. Caching & performance optimization\r\n    > Cache invalidation, custom headers, Doctrine tips, PHP-PM, Blackfire\r\n\r\n12. Advanced Usage\r\n    > Custom operations/controllers, DTOs, custom filters, data providers/persisters, CQRS, ...\r\n\r\n13. How do I?\r\n    > Enable MongoDB, ElasticSearch, NelmioApiDocBundle, Mercure, file uploads, ...\r\n\r\n14. Troubleshooting\r\n    > Docker issues, Nginx issues, JMS serializer issues, links to SF Slack / Stackoverflow\r\n\r\nA more detailed reorganization is available [on this gist](https://gist.github.com/bpolaszek/db21e8ea246694c9bbb8aee6a8f92ccc).\r\n\r\nWhat do you think?\r\n\r\n**Sorry for the long post!**  😅"},"comment":{"url":"https://api.github.com/repos/api-platform/docs/issues/comments/535851540","html_url":"https://github.com/api-platform/docs/issues/884#issuecomment-535851540","issue_url":"https://api.github.com/repos/api-platform/docs/issues/884","id":535851540,"node_id":"MDEyOklzc3VlQ29tbWVudDUzNTg1MTU0MA==","user":{"login":"alanpoulain","id":10920253,"node_id":"MDQ6VXNlcjEwOTIwMjUz","avatar_url":"https://avatars1.githubusercontent.com/u/10920253?v=4","gravatar_id":"","url":"https://api.github.com/users/alanpoulain","html_url":"https://github.com/alanpoulain","followers_url":"https://api.github.com/users/alanpoulain/followers","following_url":"https://api.github.com/users/alanpoulain/following{/other_user}","gists_url":"https://api.github.com/users/alanpoulain/gists{/gist_id}","starred_url":"https://api.github.com/users/alanpoulain/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alanpoulain/subscriptions","organizations_url":"https://api.github.com/users/alanpoulain/orgs","repos_url":"https://api.github.com/users/alanpoulain/repos","events_url":"https://api.github.com/users/alanpoulain/events{/privacy}","received_events_url":"https://api.github.com/users/alanpoulain/received_events","type":"User","site_admin":false},"created_at":"2019-09-27T08:45:35Z","updated_at":"2019-09-27T08:45:35Z","author_association":"MEMBER","body":"Yes, but I think, most of the time, users have already their own Docker images and want to use API Platform in existing projects.\r\nUsers starting from scratch by using the distribution images should not represent a lot of people (but it's hard to measure)."}}
other: {"actor":{"display_login":"alanpoulain"}}