Hey everybody! If you always wanted to contribute to core, but didn't feel up to writing the PHP for it, here's a great way you can help out: We need somebody to go through our five introductory tutorials, and make sure they are up to date with SS3, as well as using the new default theme: http://open.silverstripe.org/ticket/7023
These tutorials are the entry point for many of our developers, so you have the chance to make a big impact to the overall product. Note: We're not looking for a complete rewrite, simply maintenance and clarification.
If you are keen, please let me know and we can go through the details!
I really would like to work on this but I think I won't be fast... if completion in "the next weeks" is ok, I can do this.
I like that the tutorial starts from a bare template at the moment and creates a menu from scratch. Maybe we should
create a new tutorial skin to start from?
I have many more ideas but I would first concentrate on making it work. The most annoying work will be making
the new screenshots...
Andy
Am Mittwoch, 14. März 2012 14:48:34 UTC+1 schrieb Ingo Schommer:
> Hey everybody! If you always wanted to contribute to core,
> but didn't feel up to writing the PHP for it, here's a great way you can > help out:
> We need somebody to go through our five introductory tutorials, and make
> sure they are up to date with SS3, as well as using the new default theme:
> http://open.silverstripe.org/ticket/7023
> These tutorials are the entry point for many of our developers,
> so you have the chance to make a big impact to the overall product.
> Note: We're not looking for a complete rewrite, simply maintenance and > clarification.
> If you are keen, please let me know and we can go through the details!
Just a thought but could Capybara be used to automate the screenshotting? It would mean writing a script to drive the browser but it would mean that future 're screenshotting' could be done more easily
Hey Andy, I think "next weeks" is a fine, as long as it doesn't get into "next months" (plural) Don't you love open source deadline agreements? ;)
It'd be good to see some work in progress fairly soon though. And I'm still open to other offers if they can start sooner, it sounds like a big enough task to benefit from collaboration.
On starting with a bare theme, my motivation is mostly the maintenance overhead - I don't want to maintain a fork of the 'simple' theme just for the tutorials. This forking lead us to the current situation of having two visually quite distinct default skins (blackcandy and tutorial) in the first place.
But also: The theme markup is simple enough to use as a tutorial, and overall I think that SS newbies will learn faster if they can tinker with (smaller) existing stuff anyway, than if they have to copypaste template fragments from a website into the right place.
As far as CSS goes, I would suggest that we remove all related instructions from the tutorials - its not about learning CSS after all, and even the 'simple' theme CSS is way too complex for that. We should limit our focus to filesystem conventions, and how its included in SS.
On Wednesday, 14 March 2012 at 5:48 PM, Andy Adiwidjaja wrote: > Hi Ingo,
> I really would like to work on this but I think I won't be fast... if completion in "the next weeks" is ok, I can do this.
> I like that the tutorial starts from a bare template at the moment and creates a menu from scratch. Maybe we should > create a new tutorial skin to start from?
> I have many more ideas but I would first concentrate on making it work. The most annoying work will be making > the new screenshots...
> Andy
> Am Mittwoch, 14. März 2012 14:48:34 UTC+1 schrieb Ingo Schommer: > > Hey everybody! If you always wanted to contribute to core, > > but didn't feel up to writing the PHP for it, here's a great way you can help out: > > We need somebody to go through our five introductory tutorials, and make > > sure they are up to date with SS3, as well as using the new default theme: > > http://open.silverstripe.org/ticket/7023
> > These tutorials are the entry point for many of our developers, > > so you have the chance to make a big impact to the overall product. > > Note: We're not looking for a complete rewrite, simply maintenance and clarification.
> > If you are keen, please let me know and we can go through the details!
> > Thanks! > > Ingo
> -- > You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group. > To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/BziuzeSKXXsJ. > To post to this group, send email to silverstripe-dev@googlegroups.com (mailto:silverstripe-dev@googlegroups.com). > To unsubscribe from this group, send email to silverstripe-dev+unsubscribe@googlegroups.com (mailto:silverstripe-dev+unsubscribe@googlegroups.com). > For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
> Just a thought but could Capybara be used to automate the screenshotting? It would mean writing a script to drive the browser but it would mean that future 're screenshotting' could be done more easily
PHP-WebDriver is another option for that, which has the advantage of being in PHP.
It would end up being a lot more work than just taking screenshots, but you're right about maintainability. If someone was keen to try one of these tools out, they might want to work with Andy to produce a suitable set of scripts.
Am Mittwoch, 14. März 2012 18:23:27 UTC+1 schrieb Ingo Schommer:
> Hey Andy, I think "next weeks" is a fine,
> as long as it doesn't get into "next months" (plural)
> Don't you love open source deadline agreements? ;)
> It'd be good to see some work in progress fairly soon though.
I'm planning to make it work first and then make improvements. I will start asap.
> On starting with a bare theme, my motivation is mostly the maintenance > overhead - I don't want to maintain a fork of the 'simple' theme just for > the tutorials.This forking lead us to the current situation of having two > visually quite distinct default skins (blackcandy and tutorial) in the > first place.
Ok.
> But also: The theme markup is simple enough to use as a tutorial, and > overall I think that SS newbies will learn faster if they can tinker with > (smaller) existing stuff anyway, than if they have to copypaste template > fragments from a website into the right place.
Ok, I have some experience with students learning silverstripe with the tutorials. They began to understood the structure of the silverstripe objects when they wrote code themselves, even when they copied it. But I can show that on top of the theme, maybe with a content listing.
> As far as CSS goes, I would suggest that we remove all related > instructions from the tutorials - its not about learning CSS after all, and > even the 'simple' theme CSS is way too complex for that. We should limit > our focus to filesystem conventions, and how its included in SS.
I don't think automatic screenshots will help here. The screenshots must be annotated and cropped. I will try to make updating screens easier in the future.
Cheers,
Andy
Am Mittwoch, 14. März 2012 21:16:43 UTC+1 schrieb Sam Minnée:
> On 15/03/2012, at 6:21 AM, Gordon Anderson wrote:
> > Just a thought but could Capybara be used to automate the > screenshotting? It would mean writing a script to drive the browser but it > would mean that future 're screenshotting' could be done more easily
> PHP-WebDriver is another option for that, which has the advantage of being > in PHP.
> It would end up being a lot more work than just taking screenshots, but > you're right about maintainability. If someone was keen to try one of > these tools out, they might want to work with Andy to produce a suitable > set of scripts.
One question: Is the theme that is used on http://doc.silverstripe.org/ available somewhere so I can preview the documentation with the theme?
Another question: The simple theme uses the <% control %>-Syntax. Is this intentionally to support ss2.4? Should this be changed, as I want
to write about the new syntax?
Andy
Am Mittwoch, 14. März 2012 14:48:34 UTC+1 schrieb Ingo Schommer:
> Hey everybody! If you always wanted to contribute to core,
> but didn't feel up to writing the PHP for it, here's a great way you can > help out:
> We need somebody to go through our five introductory tutorials, and make
> sure they are up to date with SS3, as well as using the new default theme:
> http://open.silverstripe.org/ticket/7023
> These tutorials are the entry point for many of our developers,
> so you have the chance to make a big impact to the overall product.
> Note: We're not looking for a complete rewrite, simply maintenance and > clarification.
> If you are keen, please let me know and we can go through the details!
> One question: Is the theme that is used on http://doc.silverstripe.org/ available somewhere so I can preview the documentation with the theme?
> Another question: The simple theme uses the <% control %>-Syntax. Is this intentionally to support ss2.4? Should this be changed, as I want > to write about the new syntax?
On Thursday, 15 March 2012 at 1:35 AM, Sam Minnée wrote: > I think that's because the simple theme developer didn't know about the new controls. We should patch the theme to use the 3.0 commands.
> On 15/03/2012, at 1:00 PM, Andy Adiwidjaja wrote:
> > One question: Is the theme that is used on http://doc.silverstripe.org/ available somewhere so I can preview the documentation with the theme?
> > Another question: The simple theme uses the <% control %>-Syntax. Is this intentionally to support ss2.4? Should this be changed, as I want > > to write about the new syntax?
> -- > You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group. > To post to this group, send email to silverstripe-dev@googlegroups.com (mailto:silverstripe-dev@googlegroups.com). > To unsubscribe from this group, send email to silverstripe-dev+unsubscribe@googlegroups.com (mailto:silverstripe-dev+unsubscribe@googlegroups.com). > For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
What about the doc.silverstripe.org-Theme, is it available somewhere? I would like to test different image sizes and to use features like the information boxes:
It uses the sapphiredocs module: https://github.com/silverstripe/silverstripe-sapphiredocs The doc.ss.org codebase itself isn't open source (simply because we didn't have time or demand for it), but it uses more or less standard sapphiredocs, so you should be able to get close enough.
> What about the doc.silverstripe.org-Theme, is it available somewhere? I would like to test different image sizes and to use features like the information boxes:
> <div class="notice" markdown='1'> > </div>
> Andy
> -- > You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group. > To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/2A1mN_gpqkIJ. > To post to this group, send email to silverstripe-dev@googlegroups.com (mailto:silverstripe-dev@googlegroups.com). > To unsubscribe from this group, send email to silverstripe-dev+unsubscribe@googlegroups.com (mailto:silverstripe-dev+unsubscribe@googlegroups.com). > For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
Am Donnerstag, 15. März 2012 22:34:18 UTC+1 schrieb Ingo Schommer:
> It uses the sapphiredocs module: > https://github.com/silverstripe/silverstripe-sapphiredocs > The doc.ss.org codebase itself isn't open source (simply because we > didn't have time or demand for it),
> but it uses more or less standard sapphiredocs, so you should be able to > get close enough.
Ah, sorry. I installed the sapphiredocs module, but I did it wrong (with a theme) so I got a plain view - I thought this is intentional and I am missing a theme.
no problem, I mainly worked on the child-theme topic which I saw as a precondition for the tutorial. But overall I hadn't enough time last week. So, I'm happy with any help. I looked at your branch and it looks good, I will integrate it into my branch.
Andy
Am Sonntag, 25. März 2012 22:46:12 UTC+2 schrieb Cam Findlay:
Cheers... ok I will keep working on the tutorials section then... in a similar boat... Uni assignments coming up this week but should be free to make progress next week... keep an eye on the branch :)
I can see some of the tutorials need to be changed slightly due to the new layouts etc and that the page editing panels are now split up into separate menu items.
Will keep you posted here, maybe get together on Skype to go over things soon?
Actually took quite a while as the changes in the Page and Edit page layouts in the CMS from 2.4 is quite different and had to be reworded.
Same with the idea that we are not starting from a blank template... again lots of rewording and dropping out irrelevant stuff... I can see this might continue to take a while but at least a little progress made.
On Thursday, 15 March 2012 02:48:34 UTC+13, Ingo Schommer wrote:
> Hey everybody! If you always wanted to contribute to core, > but didn't feel up to writing the PHP for it, here's a great way you can > help out: > We need somebody to go through our five introductory tutorials, and make > sure they are up to date with SS3, as well as using the new default theme: > http://open.silverstripe.org/ticket/7023
> These tutorials are the entry point for many of our developers, > so you have the chance to make a big impact to the overall product. > Note: We're not looking for a complete rewrite, simply maintenance and > clarification.
> If you are keen, please let me know and we can go through the details!
It "flows" and reads well in general - although I think you can still combine sentences into larger paragraphs to visually form more logical units - it looks quite disjoint and "bullet-pointy" at the moment.
The (sub-)headlines need some work, it should be easy to determine what the article is about by scanning through them. The hierarchy is also a bit off, e.g. "Highlighting the current page" shouldn't be on the same level as "the navigation system" (its a sub-chapter of it).
Anybody else keen to review? I would be particularly interested in feedback from any of your dev friends who have a working knowledge of PHP, but haven't used SS yet.
> Actually took quite a while as the changes in the Page and Edit page layouts in the CMS from 2.4 is quite different and had to be reworded.
> Same with the idea that we are not starting from a blank template... again lots of rewording and dropping out irrelevant stuff... I can see this might continue to take a while but at least a little progress made.
> On Thursday, 15 March 2012 02:48:34 UTC+13, Ingo Schommer wrote: > Hey everybody! If you always wanted to contribute to core, > but didn't feel up to writing the PHP for it, here's a great way you can help out: > We need somebody to go through our five introductory tutorials, and make > sure they are up to date with SS3, as well as using the new default theme: > http://open.silverstripe.org/ticket/7023
> These tutorials are the entry point for many of our developers, > so you have the chance to make a big impact to the overall product. > Note: We're not looking for a complete rewrite, simply maintenance and clarification.
> If you are keen, please let me know and we can go through the details!
> Thanks! > Ingo
> -- > You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group. > To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/sQNZxUx7k6AJ. > To post to this group, send email to silverstripe-dev@googlegroups.com. > To unsubscribe from this group, send email to silverstripe-dev+unsubscribe@googlegroups.com. > For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
Hey Cam and Andi, how's the tutorial rewrite coming along? You know that you can split up and just work on different tutorials at the same time, right? :) I've written up a ticket with some further details: http://open.silverstripe.org/ticket/7157
That was done by quickly browsing through the tutorials, but looking forward to your suggestions how we can demonstrate the core concepts more effectively - we don't have to rigidly follow every code example from the old tutorials if it doesn't make sense any more in 3.0. One example is tutorial 5: It should really use ModelAdmin to show off GridField (formerly ComplexTableField), because its such a popular feature in SilverStripe.
sorry that I was so slow in responding and working, this is the first week I can work on this topic again. I think we have to work in incremental steps:
1. Make the tutorial work for 3.0 (remove wrong and deprecated stuff, make use of simple theme, work on the issues on the ticket) 2. Make better use of the core concepts 3. Add features, do things differently
For example I think it is necessary to introduce a DropdownField in tutorial 2 but this is level 2. I think it is better to use the child theme stuff but this is level 3. I will try to push the level 1 work on every tutorial in the next days.
I reviewed Cam's version of tutorial 1 and everything works.
Any feedback is welcome, I have some technical questions: - How should I merge Cam's changes into my fork? I tried a git merge, but this leads to a "merge commit". Or should we both make separated pull requests? - Tutorial 2 sets the icons in the cms. Should I copy these icons from the tutorial theme to the simple theme? Or to the docs-folder? - Is the usage of DataObject::get_one still correct? In this case it is not needed at all but I will think about a better use of the datamodel-api later.
@Cam: I will continue with tutorial 4.
@Ingo: Maybe we could couple tutorial 3 and 5 by implementing student applications as the form example? As we have to rewrite tutorial 5 completely - maybe we should implement a completely different application like the job board example in the book?
Cheers
Andy
Am Montag, 16. April 2012 10:07:02 UTC+2 schrieb Ingo Schommer:
> Hey Cam and Andi, how's the tutorial rewrite coming along? > You know that you can split up and just work on different tutorials at the > same time, right? :) > I've written up a ticket with some further details: > http://open.silverstripe.org/ticket/7157
> That was done by quickly browsing through the tutorials, but looking > forward to > your suggestions how we can demonstrate the core concepts more effectively > - > we don't have to rigidly follow every code example from the old tutorials > if it doesn't make sense any more in 3.0. One example is tutorial 5: > It should really use ModelAdmin to show off GridField (formerly > ComplexTableField), > because its such a popular feature in SilverStripe.
> sorry that I was so slow in responding and working, this is the first week I can work on this topic again. I think we have to work in incremental steps:
That's OK, the ticket I wrote can be split up if its more convenient.
> Any feedback is welcome, I have some technical questions: > - How should I merge Cam's changes into my fork? I tried a git merge, but this leads to a "merge commit". Or should we both make separated pull requests?
Merge commits are fine, they help git figure out the best merging stategy going forward. It means we can't easily merge your two codebases in isolation, but that's acceptable. Might be more efficient to work on one remote though (one of you can give the other push rights on his repo fork).
> - Tutorial 2 sets the icons in the cms. Should I copy these icons from the tutorial theme to the simple theme? Or to the docs-folder?
Hmm, yeah lets copy them into the theme, as it makes copypaste easier. Means we'll have to do the same dance when using a different theme for the tutorial in the future, but that's fine. We could also link to http://www.famfamfam.com/lab/icons/silk/ for more icons.
> - Is the usage of DataObject::get_one still correct? In this case it is not needed at all but I will think about a better use of the datamodel-api later.
Yep, should be DataList::create().
> @Ingo: Maybe we could couple tutorial 3 and 5 by implementing student applications as the form example? As we have to rewrite tutorial 5 completely - maybe we should implement a completely different application like the job board example in the book?
Yep, they're both fairly close to realistic use cases (registration/submission and catalogue-style). Feel free to get inspired by code from the book, just don't copypaste anything directly (I would let you, but my publisher won't…).
I'll review your tutorial 2 as well... time is pretty short for me at the moment with uni assessments due again but I'll start looking into tut 3 and 5. As Ingo mentions perhaps some sort of joint 3/5 tutorial might be good... perhaps we can come up with a scenario that demonstrates the same concepts but leaves the user with something tangible they can use for their own site?
Job board could work, are there any other commonly used things that might be better? I guess we just need to make sure that each of the data-relationships are represented (has_one, has_many and many_many). How about some sort of community events posting thing? has_one - date, time & location, has_many - attendees (that can rsvp via the form we set up in tut3), many_many - tags?
The merge stuff between doc content will be an interesting one... perhaps we strip the entire docs folder out into its own repo (maybe on the silverstripe github) with push rights for those of us working on it? then a final move of the content back into sapphire/framework once it is deemed useable by the public?
On Wednesday, 18 April 2012 11:39:54 UTC+12, Andy Adiwidjaja wrote:
> Hey Ingo and Cam,
> sorry that I was so slow in responding and working, this is the first week > I can work on this topic again. I think we have to work in incremental > steps:
> 1. Make the tutorial work for 3.0 (remove wrong and deprecated stuff, make > use of simple theme, work on the issues on the ticket) > 2. Make better use of the core concepts > 3. Add features, do things differently
> For example I think it is necessary to introduce a DropdownField in > tutorial 2 but this is level 2. I think it is better to use the child theme > stuff but this is level 3. I will try to push the level 1 work on every > tutorial in the next days.
> I reviewed Cam's version of tutorial 1 and everything works.
> Any feedback is welcome, I have some technical questions: > - How should I merge Cam's changes into my fork? I tried a git merge, but > this leads to a "merge commit". Or should we both make separated pull > requests? > - Tutorial 2 sets the icons in the cms. Should I copy these icons from the > tutorial theme to the simple theme? Or to the docs-folder? > - Is the usage of DataObject::get_one still correct? In this case it is > not needed at all but I will think about a better use of the datamodel-api > later.
> @Cam: I will continue with tutorial 4.
> @Ingo: Maybe we could couple tutorial 3 and 5 by implementing student > applications as the form example? As we have to rewrite tutorial 5 > completely - maybe we should implement a completely different application > like the job board example in the book?
> Cheers
> Andy
> Am Montag, 16. April 2012 10:07:02 UTC+2 schrieb Ingo Schommer:
>> Hey Cam and Andi, how's the tutorial rewrite coming along? >> You know that you can split up and just work on different tutorials at >> the same time, right? :) >> I've written up a ticket with some further details: >> http://open.silverstripe.org/ticket/7157
>> That was done by quickly browsing through the tutorials, but looking >> forward to >> your suggestions how we can demonstrate the core concepts more >> effectively - >> we don't have to rigidly follow every code example from the old tutorials >> if it doesn't make sense any more in 3.0. One example is tutorial 5: >> It should really use ModelAdmin to show off GridField (formerly >> ComplexTableField), >> because its such a popular feature in SilverStripe.
> I'll review your tutorial 2 as well... time is pretty short for me at the moment with uni assessments due again but I'll start looking into tut 3 and 5. As Ingo mentions perhaps some sort of joint 3/5 tutorial might be good... perhaps we can come up with a scenario that demonstrates the same concepts but leaves the user with something tangible they can use for their own site?
The reason tutorial 5 exists is that we developed ModelAdmin and related features after 2.0, and didn't want to alter the previous tutorials. Its an important enough aspect of the system to bring it in earlier if it fits into the "story" of the tutorial IMHO.
> Job board could work, are there any other commonly used things that might be better? I guess we just need to make sure that each of the data-relationships are represented (has_one, has_many and many_many). > How about some sort of community events posting thing? has_one - date, time & location, has_many - attendees (that can rsvp via the form we set up in tut3), many_many - tags?
One thing I learned the hard way writing the book: Write up the code examples first, its very easy to come up with examples which require too much code to explain them, watering down the message. E.g. you don't want to set up another RSVP form submission if you've already explained the form API in an earlier tutorial, stuff like that. I also think its important to choose a domain model that's clear enough so you can explain it in a single sentence - there should be no logical ambiguity about if something's a has_many or many_many for example.
> The merge stuff between doc content will be an interesting one... perhaps we strip the entire docs folder out into its own repo (maybe on the silverstripe github) with push rights for those of us working on it? then a final move of the content back into sapphire/framework once it is deemed useable by the public?
You won't have any merge conflicts when merging in code changes, only from files you both modified (in /docs). That's why I suggested to decide on one repo and give the respective other commit access. I would advise against stripping it out into its own repo, as you won't be able to submit (and update) pull requests to us easily.
My time is super limited now till the end of June... I'll see what I can get done... perhaps if we just keep it all simple and just update the existing tutorials as they are to incorporate the new SS3.0 features.
Perhaps a full review of this section would be good once things have stablised with 3.0 and some better tutorials which showcase and teach the changes to the framework could be looked at.
I'm happy to write and explain if someone can come up with the multi-part tutorial code example.
On Saturday, 21 April 2012 21:28:30 UTC+12, Ingo Schommer wrote:
> Hey guys,
> On 19/04/2012, at 11:27 PM, camfindlay wrote:
> I'll review your tutorial 2 as well... time is pretty short for me at the > moment with uni assessments due again but I'll start looking into tut 3 and > 5. As Ingo mentions perhaps some sort of joint 3/5 tutorial might be > good... perhaps we can come up with a scenario that demonstrates the same > concepts but leaves the user with something tangible they can use for their > own site?
> The reason tutorial 5 exists is that we developed ModelAdmin and related > features after 2.0, > and didn't want to alter the previous tutorials. Its an important enough > aspect of the system > to bring it in earlier if it fits into the "story" of the tutorial IMHO.
> Job board could work, are there any other commonly used things that might > be better? I guess we just need to make sure that each of the > data-relationships are represented (has_one, has_many and many_many). > How about some sort of community events posting thing? has_one - date, > time & location, has_many - attendees (that can rsvp via the form we set up > in tut3), many_many - tags?
> One thing I learned the hard way writing the book: Write up the code > examples first, > its very easy to come up with examples which require too much code to > explain them, > watering down the message. E.g. you don't want to set up another RSVP form > submission > if you've already explained the form API in an earlier tutorial, stuff > like that. > I also think its important to choose a domain model that's clear enough so > you > can explain it in a single sentence - there should be no logical ambiguity > about if something's a has_many or many_many for example.
> The merge stuff between doc content will be an interesting one... perhaps > we strip the entire docs folder out into its own repo (maybe on the > silverstripe github) with push rights for those of us working on it? then a > final move of the content back into sapphire/framework once it is deemed > useable by the public?
> You won't have any merge conflicts when merging in code changes, > only from files you both modified (in /docs). That's why I suggested > to decide on one repo and give the respective other commit access. > I would advise against stripping it out into its own repo, > as you won't be able to submit (and update) pull requests to us easily.
Completely understand that you're time is limited. If you have any work in progress, perhaps you want to submit a pull request, so that someone else can help work on it as well if they have time?
> My time is super limited now till the end of June... I'll see what I can get done... perhaps if we just keep it all simple and just update the existing tutorials as they are to incorporate the new SS3.0 features.
> Perhaps a full review of this section would be good once things have stablised with 3.0 and some better tutorials which showcase and teach the changes to the framework could be looked at.
> I'm happy to write and explain if someone can come up with the multi-part tutorial code example.
