Symphony.

Hello. I am a noob, but I’m trying to quit. Sometimes, that turns out to be harder than expected.

If you’re not familiar with The Curse of Knowledge, it can basically be summed up thus: “The more you understand something, the easier it is to forget that others don’t understand it nearly as well as you do.” I think there’s more than a little bit of this happening in the Symphony guides. I’m undoubtedly a beginner, so let’s look at a bit from the beginner’s guide:

You’d start by creating a section called, say, “Blog Posts,” and adding fields like “Title,” “Body,” and “Date.” That quickly, you’d have modeled your first content type. After creating a test entry in Blog Posts, you’d want to be able to see it on the front end. So you’d create a page called “View Blog Post” with a URL handle of post, and configure it to accept a URL parameter called “title.” Next, you’d create a data source to fetch from Blog Posts the entry whose title field matched the title parameter set in the page’s URL. Finally, you’d whip up a quick page template to display your data source’s result.

As someone unfamiliar with either Symphony or MVC, I run into a number of problems: I don’t know what sections or fields are for. I don’t know what it means to model a content type. I don’t know what you mean by URL handle and paramenter. I don’t know what a data source is. I can only vaguely guess at what a page template is. In short, the jargon sent the entire thing sailing over my head, and it’s a complete turn-off. And no, the visual overview doesn’t clear anything up.

So I urge you to rethink at least the beginner’s guide. Introduce concepts clearly, only giving them a name after you’ve thoroughly explained them. E.g. “Web pages are made of many different pieces, each of which holds a particular kind of content: Headers, footers, blog posts, picture galleries, etc. In Symphony, we call these Sections.” No idea if that’s accurate, but you see what I mean.

I know that Symphony is capable of more than web pages, but it’s good to start with a concrete example that people can wrap their heads around first, then expand later. Science teachers start teaching about electrons with concentric circles orbiting a nucleus. They don’t dive straight into probability clouds. :)

On the other hand, the Hello World tutorial was much, much easier to understand, and I urge you to get new users there as quickly as possible.

Symphony looks crazy powerful, so I’m going to stick with it, but for now I’ll leave you with a video that might make you feel how I did when I read the beginner’s guide: Rockwell Automations Retro Encabulator ;)

I think the problem is most how-to guides are written in the understanding that you will go from one guide to the next and won’t skip around.

The problem is it doesn’t tend to happen like that.

There are a number of things the devs of Symphony could do but one idea I’m planning on using on future jargon-heavy websites is tool tips, some with screenshots where necessary, instead of glossaries.

Imagine you’re reading a how-to guide and it mentions data sources. On the page the words are in bold and by clicking (or hovering if you fancy) on the word a large tool-tip will pop up. The tool tip will contain a brief description of what a data source is and a link to find out more about them.

Where things like input field are mentioned the tooltip can contain a cropped screenshot.

This would make the whole learning process much quicker as they wouldn’t necessarily need to jump from section to section.

Of course, the best option would be chaptered screencasts similar to what Apple does on their website when teaching people about using a Mac. The vast majority of people, especially non-developers, learns best by seeing.

Thanks, Tonamel, and welcome. We appreciate your feedback. It’s worth noting, though, that every term you say you don’t understand in the Beginner’s Guide is linked to a very thorough explanation of the concept elsewhere in the docs.

That said, your point is certainly well taken. The challenge of something like a Beginner’s Guide is that beginner is a relative term. It could be someone who’s a very experienced PHP developer but has never used Symphony. On the other hand, it could be someone who’s using the internet for the first time ;) Obviously, what works for one will not work for the other. So our approach was to try and make a guide that would be most helpful for the greatest number of people.

If we’ve failed to create documentation that’s helpful to you, I apologize. Please note that the Learn section has just been launched and is very much a work in progress. Hopefully, as it matures, we’ll be able to provide content that meets everyone’s needs. Feedback like this will help :)

If you’re not familiar with The Curse of Knowledge, it can basically be summed up thus: “The more you understand something, the easier it is to forget that others don’t understand it nearly as well as you do.”

Well that puts us in a pickle; you have pinpointed the problem. The solution, however, is not as obvious.

Everyone learns differently, but the core of the problem is that the people that have documented Symphony in the past have been more experienced users. I was involved in the process not long ago.

It’s not easy to create something based on the perception of others. The obvious solution is to generalize and categorize groups of people, but it’s not perfect as you have pointed out.

I devoted a significant portion of my time to developing Symphony documentation, as have others. For me, it was easy as I learned new things to document them. I documented them in a way that I learned. Some of my documentation really hit home. However, the more advanced and experienced with Symphony I became, the more difficult it was to document.

You see, documenting Symphony was fun early on. I also was and still am devoted to the CMS. But, the harder it became, the less I documented. I still enjoy documenting Symphony, but it’s at a more experienced level.

Up until Craig was brought on by the development team, there were not enough novice users willing to commit to the huge task of formal documentation. For those of us that tried, we soon lost steam as our experience grew (as I mentioned earlier).

Craig is an experienced Symphony user so feedback from novice users will always be critical. The documentation is not perfect and it will never be; it will always be in a state of evolution, as will the CMS itself.

Nevertheless, know that Craig has made leaps and bounds with the documentation recently and he is listening.

Thanks for the speedy responses!

It’s worth noting, though, that every term you say you don’t understand in the Beginner’s Guide is linked to a very thorough explanation of the concept elsewhere in the docs.

I can’t deny that! (Except URL handle. That’s not linked anywhere.) My point was more that the chance of a new user reading those pages before they read through the Beginner’s Guide page is pretty low, so you shouldn’t write it as if they have.

I’ve been puzzling it over in my head what’s been preventing me from getting my metaphorical foot in the door. I’ve made several attempts (check my registration date o_O), but I never even made it as far as installing a test version somewhere because the documentation was so completely overwhelming. I think I may have figured it out, though. I don’t know what it means to model content. And from what I gather, that’s a pretty important concept in Symphony. I’d love to see a guide describing what modeling content is, then dissecting a web page to show which content has been modeled/how it’s modeled/where all the content comes from.

But as I said before, the Hello World tutorial is great, and should be one of the first things noobs like me see when they go to the Learn section of the site. I’m finally starting to grasp how the whole thing works. And I’m glad I took the time to go through it, because the Beginner’s Guide nearly scared me off. Again.

Feedback like this will help :)

Glad to hear it! And I look forward to what fancy tutorials the future will bring :)

Except URL handle. That’s not linked anywhere.

Thanks for pointing that out.

the chance of a new user reading those pages before they read through the Beginner’s Guide page is pretty low, so you shouldn’t write it as if they have.

The thinking wasn’t that they’d have already read it, but that if they didn’t understand the term, they’d click the link. We’ll have to consider how to make this more obvious…

I don’t know what it means to model content… I’d love to see a guide describing what modeling content is…

This is a good idea. In the meantime, here’s a shot at explaining it: Let’s say you want to build a blog. Your blog’s content, like that of all blogs, will consist of posts. So Blog Posts are a type of content you want to manage in Symphony.

Because Symphony allows you to build and manage any kind of content you want, there isn’t any assumed structure for a blog post. So you’ve got to ask yourself, what does a Blog Post consist of? For your purposes, maybe each one will have the following fields: a Title, a Body, a Date, and some Tags.

You’ve more or less just modeled your first content type. In Symphony, modeling content simply means figuring out what kinds of content you need to manage (these translate to Sections) and what each will look like (i.e. what fields it will contain). Of course, there are a few more technical details to it than that, but that’s the basic idea. Hope that’s helpful :)

The funny thing is: in my experience, most people starting with symphony already grasp the concepts of a database like mysql. The way symphony is built (sections, fields, datasources etc) actually follows the concepts of a database quite well. A field looks like a row, a section behaves like a table, datasources are the pieces of php code that get the data from the database, etc.

It took me a few hours of messing around with symphony to fully realise this. But since then I realised symphony could really be used for practically everything I would use a database for.

Maybe we could have a new documentation page like “the basics of symphony for those that are familiar with mysql”. I know it would have made my life a lot easier!

Maybe that way it becomes more clear that you really manage content, like in a database, instead of pages, posts, etc.

Maybe we could have a new documentation page like “the basics of symphony for those that are familiar with mysql”.

The beauty of how we set up the guides section is that, in addition to the three core guides, we can add any number of specialized guides, such as the one you’re suggesting. Just have to find time to write them ;)

In Symphony, modeling content simply means figuring out what kinds of content you need to manage (these translate to Sections) and what each will look like (i.e. what fields it will contain).

Nicely defined!

Just have to find time to write them ;)

If you need help, let me know!

A field looks like a row, a section behaves like a table, datasources are the pieces of php code that get the data from the database, etc.

A field looks like a column, no? Is it the same thing?

2 quick points to add:

1. My aha moment was figuring out the data modeling nomenclature (Section = Table, Entry = record, field = field, datasource = query)
2. Understanding Symphony necessarily turns on understanding the basics of an XSL transformation, something many new users are not familiar with. I think starting there and building out to describe how Symphony accommodates using the transformation as a CMS engine might work.

My aha moment was figuring out the data modeling nomenclature (Section = Table, Entry = record, field = field, datasource = query)

My thoughts exactly. When I recommend symphony to people this is normally the first thing I say to explain why it’s so flexible. The xslt part comes after that, like: “Oh, you will have to learn xslt, but it’s worth it!”

Understanding Symphony necessarily turns on understanding the basics of an XSL transformation, something many new users are not familiar with. I think starting there and building out to describe how Symphony accommodates using the transformation as a CMS engine might work.

When I started with symphony I thought the focus in the docs was way too much on the xslt part. Mostly because all xslt does is turn the data from the system into something that looks good. But yeah, you do need the data you want before you can worry about the looks of it..

Anyhow, I think this has been picked up very nicely with the new docs, keep up the good work!

If you need help, let me know!

Yeah, we’ve been thinking through what the procedures and guidelines will be for community-contributed documentation. Will let you know when we’ve got it all figured out.

My aha moment was figuring out the data modeling nomenclature (Section = Table, Entry = record, field = field, datasource = query)

Andrew, that’s exactly what helped me out to understand the basics of Symphony. :) It could be helpful as well to think of the Select Box Link as a SQL join - at least it worked for me.

Let’s not forget that most of the registered users are already experienced and talented developers. We should take this into account as far as documentation is concerned.

There is already a significant number of guides and tutorials, but some of them requires knowledge of the concepts behind the system. Instead of distinguish between beginner, user and developer, we could try with a different approach.

Here’s the idea: we don’t simply fall into “beginners” or “developers” categories. Our mental model is heavily influenced by what we’ve been using before Symphony. These models should be investigated in order to reduce the impact of Symphony basic principles on new developers.

Example:

Welcome aboard! Before diving into the documentation, we’d be glad to know more about your past experience as developer.

[ ] Newbie 
[x] PHP/MySQL Developer 
[ ] Wordpress user 
[ ] Textpattern user 
[ ] Drupal user 
[ ] etc.

According to the results, we should try to write articles that match the user’s mental model. For example, we have seen that the bijection between Symphony and DBMSes works well. So, given that many new users are experienced PHP/MySQL developers, there should be articles where Symphony concepts are explained by using database terminology.

Does it sound convincing?