Symphony.

I would like to see a lot more on advanced event and DS-topics like Fetching data from a section before the insert, changing other entries besides the ones in the form, custom SQL statements.

Agreed. Although strictly speaking this is “hacking” and not part of formal documentation. No reason why it can’t be covered with tutorials or walkthroughs though, since each customisation is likely to be so specific to your own requirements.

Simple: give us your use cases. When will you need to consult the docs? What will you be looking for?

Documentation on fields, extensions etc. It took/takes me ages to find out those.

Also, the first time I used symphony I would have murdered to get a very simple “use case” explaining how to create a simple website.

Great article by one the of the Django honchos on writing documentation:

http://jacobian.org/writing/good-documentation/

Yeah, Allen just sent that along this morning… Really great piece. I think our approach with the new docs fares pretty well by those standards. Hopefully, you’ll all agree ;)

Craig, I suppose will see the new documentation with the release of the new Symphony site. Could you please give us a brief overview of the structure of the documentation - maybe some kind of table of content?

Is it a complete rewrite or does it just enhance the current state of the documentation? Which kind of external resources will be integrated? (I’m thinking of a lot of stuff bauhouse has written in the past.) How will different users be addressed (newbies, advanced users, developers)?

Thanks!

I’ll try to answer your questions without taking too much time from actually working on the docs themselves ;)

Is it a complete rewrite or does it just enhance the current state of the documentation?

It’s a complete rewrite, and a completely different approach, but we were able to carry over some of the work Mark Lewis did on the existing docs.

Which kind of external resources will be integrated? (I’m thinking of a lot of stuff bauhouse has written in the past.)

We will definitely be looking to include community-contributed articles and tutorials, but they’ll carefully selected and edited. It’s important to us to make sure that there is a high level of quality and consistency throughout the documentation.

As far as community input, we’re also implementing a suggestion system throughout the docs. It won’t be ready right at launch, but soon after.

How will different users be addressed (newbies, advanced users, developers)?

That’s actually a cornerstone of the new approach. Most of the documentation section is filterable by those very audiences (Beginners, Users, Developers), meaning noobs don’t have to sift through tons of developer-level stuff, and vice versa. Edit I should note that you should anticipate developers’ stuff coming along a little more slowly than the rest because it requires a more concerted effort from the team and the community.

Could you please give us a brief overview of the structure of the documentation - maybe some kind of table of content?

Sure. It’s no longer in a book/chapter style. There are a few overarching sections: Guides, Tutorials, Articles, Concepts, and FAQs.

• Guides are the starting point for each audience and help to frame things and direct ppl to relevant resources. We’re starting with a guide for each core audience (Beginner’s Guide, User’s Guide, Developer’s Guide), but this is extensible, so we will do other kinds of guides in the future (Guide for Designers, Guide for Wordpress Converts), etc.
• Tutorials, pretty self explanatory. At launch, we’ll have an installation tutorial, a pretty basic Hello World tutorial, and whatever else I can finish in time ;)
• Articles, also self-explanatory. All of Allen’s Chaotic Pattern articles are being ported over. We also have: “The Tao of Symphony” which describes the development philosophy behind the system, “Symphony Anatomy,” “Symphony Workflows,” “Planning a Symphony Project”, “XSLT for Symphony”, something like “Advanced Symphony Techniques” and I think one other one that Allen’s working on geared toward designers. I can’t guarantee that every one of these will be done by launch, but the majority will. And then the rest soon after.
• Concepts are really the meat of the docs. Basically a comprehensive reference section.
• FAQs, well… duh ;)

Resources (screenshots, code samples, file attachments, screenshots, and so on) are used throughout the system and can be attached to most of the other elements. Also, most of the elements in the system can be cross-referenced. How this all works is that when you’re looking, say, at the “Sections” concept, you’ll see any resources that have been attached to it along with any related articles, tutorials, and so on.

There are a few other small wrinkles, but that’s the basic gist of it.

Thanks for taking the time for this walkabout. And thanks for all the work you folks are doing!

Many thanks to the Symphony team! Truly amazing! Can’t wait.

I am really looking forward to this. Ah, the excitement!

Sounds brilliant. Exactly what I need to ease me through these early stages of Symphony addiction. Looking forward to it!

It looks nice. I can’t wait to see it!

Natural Docs is a good choice..

I’ve been watching Symphony since the 1.7 days but I have always found the initial learning curve to be a bit too steep though worth the effort to learn. Symphony’s promise as a great CMS and the wonderful community that surrounds it are great inspiration to me in persevering my study of Symphony.

I have noticed I continue to return to the Beginner’s Guide hoping to find updates on those forthcoming articles; specifically Planning a Symphony Project, Symphony Workflows, and XSLT basics. I feel that these articles would be a great help to novices like myself.

I’d also like to take my first post on this forum as an opportunity to thank the community and everyone on the Symphony team. Symphony truly is a beautiful thing you’re creating.

I know, I know. Long overdue. The “Planning” article is actually about 70% done, but I just haven’t had time to finish it. I promise I will start getting these pieces up soon.

Something that might help extension developers would be to introduce a ‘since version 2.0.6’ to the delegates page, similar to how Google does it. It would help track new and deprecated delegates to developers can get a better idea of what versions of Symphony their extension will support.

Our intention is that the release history page would cover that sort of thing. We’re wary of complicating the documentation too much with all kinds of historical references…

I think that if a suitable UI could be thought out, it would be more beneficial to add such information to the actual documentation, instead of leaving it embedded in the release history.

It saves having to check in two places (or potentially each release entry) for information about the delegates.

I understand the argument there, and it’s something we strongly considered when putting together the documentation. Our problem is this: where does one draw the line? If we’re going to tack legacy info onto the Delegates concept, why not also on, say, Pages and Page Templates, which changed quite a bit with 2.0.6? Or why not then include information on the old section link field?

In the end, we thought it would be too confusing for users, and far too taxing for the team, to maintain thorough legacy info all throughout the docs.

It saves having to check in two places (or potentially each release entry) for information about the delegates.

Sure, but then the burden shifts to us to maintain yet another stream of information. Besides, if anyone can be reasonably asked to be acquainted with release history, I’d think it would be developers.

I really do think that the release history can be the appropriate place for this kind of information, and maybe what needs to happen is that we find a way to make the history more easily scannable/searchable for this sort of info, so that one can track certain kinds of changes over time. What do you think? Remember, the whole releases section is only a few months old and so I’m sure there are improvements to be made…

Our problem is this: where does one draw the line? If we’re going to tack legacy info onto the Delegates concept, why not also on, say, Pages and Page Templates, which changed quite a bit with 2.0.6? Or why not then include information on the old section link field?

Because Pages and Page Templates don’t have delegates that affect extensions. That’s a change in workflow and UI, not a change in delegates.

Besides, if anyone can be reasonably asked to be acquainted with release history, I’d think it would be developers.

Old developers maybe, but new developers who jump in at 2.0.7 probably don’t have any idea what 2.0.6 is like. Being new, they might not have the patience to look through the Release History either.

I really do think that the release history can be the appropriate place for this kind of information, and maybe what needs to happen is that we find a way to make the history more easily scannable/searchable for this sort of info, so that one can track certain kinds of changes over time.

I agree, perhaps in the meantime a section could be created called ‘Extension Changes’ that summaries delegate change information and other important information such as jQuery support.

I still maintain that I think delegate release history is better suited on the delegate page, as I think it’d be the first stop for a new developer looking for information. It makes more sense to me from a UI point of view as well.

ie. If you had whole bunch of photos about food, nature and concerts would you group them by the subject, or by when you took the photo?

Remember, the whole releases section is only a few months old and so I’m sure there are improvements to be made…

I know, we’ll get there in the end :D

I still maintain that I think delegate release history is better suited on the delegate page, as I think it’d be the first stop for a new developer looking for information. It makes more sense to me from a UI point of view as well.

Point taken. I’ll talk it over with the team. The reason I’m so hesitant is that, for me, it’s important to think about the documentation as a whole, and consistency is of the utmost importance. 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.

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.

That’s why I’m not entirely convinced by the photo metaphor. If you just want to see currently available photos, then yes, you’d probably browse by subject (which is how one browses concepts already). But in this case what’s relevant is the history. It’s as if you wanted to know which photos had been posted or updated since the last time you’d browsed. And I’d think you’d prefer a timeline rather than drilling down to each photo and looking at its date and changelog. No?