8000 Rethinking the components section · Issue #5104 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Rethinking the components section #5104

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.

Sign up for GitHub

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

Jump to bottom
Closed
wouterj opened this issue Mar 22, 2015 · 2 comments
Closed

Rethinking the components section #5104

wouterj opened this issue Mar 22, 2015 · 2 comments
Labels
Waiting feedback

Comments

@wouterj
Copy link
Member
wouterj commented Mar 22, 2015

The components section seem to be still the most confusing part of the documentation. Mostly because of the fact that it talks about both the standalone usage and the general usage of the component. This means that Symfony Framework beginners are getting confused by the "standalone" part of this documentation. But, as we don't want duplicated documentation that much, we still link to the components section from quite a few cookbook/book chapters. And google seem to like the components section as well.

We've tried fixing this in the past:

  1. Duplicate usage docs in both cookbook and components (see Console component)
  2. Move general usage docs to a seperate (component) recipe, so people won't get confused of the hassle to set the component up (see Translation component)
  3. Document both framework and standalone usage using code tabs (see Form component)
  4. Add "(Symfony X Component)" to the title

From these methods, I think (2) has been the most effective. The only disadvantage I can think of is that people would have to toggle between 2 recipes to know the usage and the framework specific features (like automatic message catalogue discovery for translations).

I would like to know what others think and if anyone can think of other solutions to this problem. To me, it is the biggest problem with the docs that we are facing at the moment.
@javiereguiluz
Copy link
Member

I agree with you that the (2) alternative should be the way to go. If I understood you right, all the documentation should be focus to explaining things around the Symfony framework ... but each component will include a separate recipe (e.g. "Using this component outside of Symfony") to explain the standalone installation procedure, any tweak needed to use it separately and any limitation of using it outside the framework.

@wouterj wouterj mentioned this issue Apr 7, 2015
Closed
3 tasks
@javiereguiluz
Copy link
Member

Closing it as "fixed" and superseded by the changes made after our documentation reorganization.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Waiting feedback
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@javiereguiluz @wouterj
0