Symphony.

I have gone through the tutorials and have found them very helpful (thanks to the authors), but even so, I needed to go over them several times to really understand what they were telling me because the tutorials were less clear than one would hope. I want to give suggestions on how to make them clearer so that others can perhaps avoid some of the problems I had with it (but which I no longer have). As such, I begin with the Hello World tutorial:

(1) The reader is told to install Symphony without including the default workspace. It does not tell the reader the reason for not including it or the way to avoid including it. Tell the reader something like: delete the workspace folder before you run the installer so you can start with an empty workspace, which is required for this tutorial.

(2) The thing the reader is made to build is not very useful. The reader can find useful things to do with the techniques, of course, but they should not have to hunt for one because one should already be smacking them in the face as they read the tutorial. Only small changes would be needed to change the objective from greeting visitors in multiple languages to giving them a Twitter-like webpage. Because the next tutorial is for a blog, this would also make for a smooth (conceptual) transition to it.

(3) The objective is stated in very abstract terms like “modeling” and “channeling”. This abstraction lets the reader expect to be creating a simple “Hello World” page because of the title of the tutorial, but when they are told to create a “couple” of greeting (or tweets), they are given pause to reconsider their apparently flawed assumption about their objective. The question, Where is the tutorial going with this?, is an unwanted distraction. Avoid it by telling them the objective in concrete terms, like: you will be building a Twitter-like webpage and your first tweet will be the infamous “Hello World”.

(4) The “Model the Content” page tells the reader that sections are created to define and model the content they will be managing. The reader will probably wonder whether defining and modeling are two different things or just two terms for the same thing. Also, the explanation is quite abstract. Tell them something more concrete, like: when you create a section, you are telling Symphony about the kind of content you will be working with so it knows how to build you an interface for working with it.

(5) When Navigation Group is mentioned, an explanation follows after three paragraphs and a screenshot. This requires the mind of the reader to backtrack. The explanation should follow on the heels of the mention so there is no need to backtrack.

(6) One last thing that has nothing to do with clarity but should still be fixed anyway: there is a spelling error on the “Grab the Data” page where it says “only field we added to or [sic] section”.

I don’t have enough time to comb through the next tutorial just yet, but I’ll come around to it later.

Thanks for the detailed comment! We’ve received quite a bit of feedback on these tutorials, and we’ll be sure to take your thoughts into consideration when we next revisit them.