More details to lower the threshold for beginners #133
Conversation
Some parts have been changed or explained more explicitly. The intention was to lower the threshold for beginners. This means, some more explanation of the namespace usage as not every developer is currently 100% familiar with its usage and we should rather take them by the hand to enjoy namespaces than scare them off.
| I think this is more readable and understandable (though for the "quick start" articles, the intention is more to attract new users than explain everything, so we also need to be sure to keep explanations brief). Before this is merged in, can you go through and add a line break (approximately) after the first word that crosses the 72nd character? Thanks for the help! |
| Hi Ryan, I tried not to add too much, but explained those things that I did not understand when I read it the first time. Because when this is your first encounter with Sf2, I would not like to generate open questions for the user. And the heavy use of namespaces already adds some uncertainties, if you are not used to it. I'll go and check the line breaks of course, thanks for the feedback. Cheers |
| Hmm, I think that it's probably not too explicit (you did a pretty good job already staying brief) - but I wanted to get that thought into your mind. If any part of this pull request is removed for being "too much", it'll probably be minor. We're already explaining a few pieces line-by-line, adding some more notes about the namespaces makes sense. Thanks :) |
| Ok, should I send a new pull request on a new branch and close this one? Or somehow try to ammend and get the changes into this one? If yes, what's the best option to do so (I'm not that advanced with mangeling with commits and pull requests yet) |
| Keep this PR, but then you have two options:
|
| hi all, I strongly cheer for additional explanations, as I am drowning in all this newness. I tried to teach myself GitHub by reading help.github.com, and they have an interesting trick for newbies. They put detailed explanations in a "more-info" div which is collapsed by default, and if you need more info, then you can expand that div and it explains it more in-depth. I would like to see that implemented in the symfony2 docs, and wish I knew enough to be able to contribute. I keep getting scared that I won't be able to figure this out. :( I was reading doc 2.0, page creation, routing, and found a typo, tried to help fix it but had to learn GitHub, then I discover it was already fixed in the Git. I posted my trial & frustration in the google group for docs. I also noticed there is not a section in this GitHub labeled "ISSUES". Would that act like a "bug" tracker? Are the Trac. and Forum. websites obsolete for version 2.0, and we should use GitHub Issues for bugs, and google groups for forum discussions / help requests? Thanks again |
| Hey Peter- I've merged this in and tweaked the spacing things. Thanks! |
| Great news, thanks! Sorry I did not get back to you earlier - I already fixed the spacing, but did not push yet. There's one more thing: |
| Hmm, yes - I see what you're talking about here (http://help.github.com/create-a-repo/ click "More about repositories"). There is a generic tag in sphinx called "admonition" (http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonition). That could be used in this way (would just require some styling/js in the template). This would need to be rendered in some intelligent way in the printed version as well. If I can think of a good place to use this, I might try it and see what Fabien says. Thanks! |
3 participants
Some parts have been changed or explained more explicitly.
The intention was to lower the threshold for beginners.
This means, some more explanation of the namespace usage as not every developer is currently 100% familiar with its usage and we should rather take them by the hand to enjoy namespaces than scare them off.