Symphony.

It may make perfect sense to you that Delegates get special treatment, but someone else might then very reasonably expect that every concept should have a changelog.

What about using something like Nick’s Entry Revision Field connected with a yet to be invented version field to handle changelogs/histories?

Well, yeah that’s the ideal implementation. Do we have time to build and maintain it? I don’t know…

Edit Also still doesn’t provide the sort of one-stop-shopping for developers that brendo’s talking about. Especially once we start adding other sorts of API stuff to the docs.

Also, as you pointed out, there are other bits of info relevant to extension developers (jQuery support being one), and that would never live on the Delegates page anyway. So you’d still have to check two places regardless.

Agreed.

And I’d think you’d prefer a timeline rather than drilling down to each photo and looking at its date and changelog. No?

That would be annoying, but at the moment, you don’t have to do that as the Delegates are all contained on a single page making use of an accordion to hide or show each one.

This the workflow that I’ve got in my head:

Developer starts making an extension and goes to the Delegates page to see what delegate they’ll use modify the head.

They find FrontendPreRenderHeaders and click on it, sweet!

They want to see if it’s available in Symphony 2.0.5, but that information isn’t available on the delegate page? Where do they go to look now? Even worse, they may just assume it’s in 2.0.5 and then get frustrated when they find out their extension isn’t working.

Assume they find the release history page (which is unlikely considering it’s in the Downloads section available only as an in-text link) how would they then find out which release contained this delegate? As you mentioned, there is no search, or interface to check this quickly. Each release has to be checked, not just 2.0.5, because it could of come out in 2.0.3 (or in this case, 2.0.6).

Does that explain it a bit better?

I’ve attached a quick Photoshop/Firebug Hack of what it could look like? I’m more then happy to help wherever necessary to get some changes rolling.

Thoughts?

Attachments:

symphony-delegates.png

Ohhhhhhhhhhhhhhhhhhhh, I see now. Yeah that makes much more sense to me.

I think that, because we agonized from the beginning over how to deal with changes docs-wide, kicking around ideas like the ones Nils proposed above, my mind was stuck in that place when you made your proposal. But what you’re proposing here is not adding some sort of revision tracker or even a changelog, but simply tacking on an additional attribute to a delegate when appropriate, which makes perfect sense to me.

Thanks for patiently explaining yourself brendo ;)

Yay, no worries czheng :)

A new tutorial is available: “Say Hello to Symphony”.

In this “Hello World” follow-up, we build out a full-featured site, with front-end submission, an RSS feed, Twitter integration, and more.

Thanks, Craig. This looks great. The multi-lingual content is a nice touch.

Craig, that’s an excellent tutorial. You’ve done some really hard work to get that out and explain a lot of concepts clearly and as free from jargon as possible.

Well done mate.

@czheng, I’m not sure if I am the target audience of this new tutorial, but I really liked the “Winnie-the-Pooh” – or “Pu der Bär” – part of it. It’s like childhood coming back :)

Thanks for the feedback fellas.

Do let me know if you find anything that could be clarified or simplified. It was a monster tutorial and so I’ve been a little worried about its overall flow and cohesiveness. Feel like I got lost in parts of it…

Now that a couple of the main intro tutorials are out of the way, I’m going to start putting together some guidelines for community-contributed tutes (I’m looking at you, Stephen). So if you’re interested in that sort of thing, start brainstorming now ;)

I really liked the “Winnie-the-Pooh” – or “Pu der Bär” – part of it.

Glad you liked that… my favorite book growing up :)

Well, while you’re looking at me, Craig, I have to admit that I’m beginning to feel outclassed by many of the developers on this forum. I’ve got so much to learn about Symphony before I can make many more tutorials.

But I am just about finished the long-overdue upgrade of my personal portfolio site from Symphony 1.5 to Symphony 2.0.7. I just finished a feature I’ve added that uses data source filtering and XSLT to create next and previous links to navigate through portfolio items in different categories. I’m thinking I’ll release the site as a portfolio ensemble, along with some cleaned up and updated content from my DesignProjectX experiment.

Plus, I find that I can better wrap my mind around things when I need to explain things to others, so I’m thinking of turning my experiments with extensions I haven’t tried and attempts at developing extensions into tutorials.

Sounds great, Stephen. No pressure, of course, on any of this. Just meant to say that we’d welcome your contributions :)

Where oh where did the overture21 / symphony21 sites with the wiki/documentation/screencasts go?

Screencasts are here, http://vimeo.com/groups/symphonycms/videos. There are not many right now

I think that Symphony is very documented along the discussion threads, but forum model has not the appropriate UX for that.

A simple idea: we could have a contextual guide, organized by themes, with links to featured threads (some of you did that on this discussion). Could be at the left sidebar of the forum, as a topic, like Actions, Browse and Categories.

I'm having my first steps in Symphony and XSLT... I know that there's no better learning than experience. But it's always good to learning from others experience and best practices in beginners situations like "how to create navigation". A contextual guide with featured discussions would help a lot in my opinion.

The API documentation is pretty complete and well done, but what's really missing in my opinion is some kind of step-by-step or how-to documentation for (extension) developers.

• How can I create a custom event or datasource?
• How can I add stuff to the xml-output?
• How to query the database in a secure manner?
• How to work with Sessions and Cookies in a consistent way?
• etc.

Developers shouldn't have to look into Symphony's core or ask the same questions in the forum over and over again.

Better documentation would make developing for and with Symphony so much easier and improve the code quality of extensions as well.

@Jens: I totally agree. If I had more time it would be a pleasure to write something about these subjects, but maybe you can start on a few of these subjects? Or, if you don't feel comfortable writing the actual articles, maybe you could start compiling a list of subjects you feel are absolutely necessary to start extension development.

I am pretty sure it will be picked up if there is a beginning.

I don't have the knowledge and insights yet to actually write a good documentation myself, but I'll make some notes on where I had a hard time figuring stuff out or searching the forum for answers while developing with Symphony.

but I'll make some notes on where I had a hard time figuring stuff out

That would be useful. Symphony as a CMS is well documented, so it's using Symphony as a framework that is less so? Probably because relatively few people need this stuff as most just use it out of the box without dipping in to PHP.

This would probably work best in cook book format, using your list above since it's not linear. It could just be a series of short explanations and gist code examples.

There might be more in the Call for help with documentation! (Don't worry, it's not difficult.) sticky.

@nick, I think it's that the usage of symhony is pretty well documented (datasources, events, sections, etc), but the extending isn't. Most of the current hardcore developers for Symphony are pretty familiar with the core, but I can imagine there is quite a big hurdle for newcomers to write their first extension.

Sure, there is the API documentation itself, but I guess that's only useful if you already understand how to do more basic stuff.

I can speak from experience that it took me quite a lot of time before I realized writing custom DS'es isn't hard at all. To be honest I was quite afraid of them in the beginning (because of the very large include file that did all the work). So, yes, a simple tutorial or guide on how to do this would have helped me a lot.