Symphony.

New and longtime users alike have been frustrated by Symphony’s lack of comprehensive, in-depth documentation. It’s raised the barrier of entry for those coming to the system for the first time, and it’s been an ongoing hindrance for more seasoned users interested in developing extensions and contributing to the core. Though community members like Mark Lewis and Stephen Bau have worked admirably to fill the gap, the truth is that documentation remains a liability.

Hopefully, not for long. A new documentation system is in the works, one that has been redesigned to accommodate everyone from beginners to established developers and that takes into account varying modes of interaction and different styles of learning. And though we’ve got a very solid foundation, we as always need your help. But first, let me give you a sense of where we’re headed:

What you can expect to see

• Comprehensive reference sections for important concepts and common tasks
• A library of tutorials and articles
• Tons of rich illustrative materials (code samples, screenshots, and screencasts galore)
• Edited guides for beginners and developers
• A commenting system for community feedback and participation
• Elegant filtering system for different levels of expertise

What you can help us with

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

Bear in mind

As Allen mentioned in his recent breakdown of the dev team’s current projects, there’s a heck of a lot going on… so, please be patient :)

And in the meantime

Beginners can check out Bauhouse’s collection of Symphony tutorials

I know this is all noob stuff, but some things like - how to display recent articles, how to display different categories, and link to articles in that categories, how to have featured articles, how to make short excerpts which would lead to complete articles…. - all those things should be explained with code samples. I’m always looking for some simple solutions but can’t find any. Wordpress sites are all covered with tutorials how to do this, and that, WITH CODING EXAMPLES, and I wonder could Symphony be more like this? I’m thinking - show us how, so we get it, and we’ll make webpages with symphony with pleasure, and not frustration.

Give us your use cases

DS Filtering

One really important thing for me is exhaustive explanations on DS filtering and Output Parameters. The syntax of filters can sometimes be cryptic, so a solid explanation with examples for each would be handy. Use cases for almost every eventuality would be a great reference. I’ll think of a list.

Some basic things people can trip up on:

• you can add multiple filters to a DS
• you can’t force them to be conditional, although if a parameter used in a DS doesn’t exist (isn’t populated with a value) then it is ignored
• the filters multiply as ANDs, not ORs

Output Parameters

One of the harder concepts to grasp is that of Output Parameters. First-time users will probably ignore them completely, instead choosing to use Data Sources which pull in all entries than using XSLT to cross-reference related entries. Using Output Params to filter related sections is a frequent topic on the forum, therefore it deserves a chunk in the documentation.

• what output parameters are
• when you would want to use them (Select Box Link filters on IDs, for example)
• importance of keeping the XML lean

For reference here are some discussions where the concept has been repeatedly explained:

• How to Build a Navigation
• DS Filtering: Pictures on articles through galleries?
• Select Box Link Weirdness
• Data source Puzzlement
• Filtering articles by newest value
• Section Link Field Type
• DS-Filtering: Problems with linked sections
• Filtering data sources
• DS Filter can I control if it filters by id or handle?
• Filtering a datasource by the values of another datasource

Master/Detail filtering

Use case: you want to have a list of entries (articles, categories etc.) and want to hyperlink each to a detail view showing that entry only. (Master/Detail Views in Symphony). Explanation can weight up: using a single or separate pages (template re-use); using a single or separate Data Sources (the ignoring of filters when params don’t exist).

Types of examples

In the forum and the documentation a lot is spoken of the default workspace: the blog. Although Articles, Categories and Comments are tidy examples, I wonder if it’s worth having more varied examples in the documentation. There is a worry people will skim the documentation and assume Articles, Categories and Comments are all Symphony can do.

Similarly there should be caution about referring to things which have since-changed. Two things spring to mind: a “Section Link” field (v2 beta and rev5) no longer exists, it has been superseded by the Select Box Link field; and the “Publish menu” and “Publish view” no longer exist now we have custom navigation groups.

Craig, you have a list I compiled of various resources/threads/tutorial ideas but I will repost it here for public consumption.

Software Resources

Could be trimmed down from this massive list. Focus on text editors and XML/XSLT tools. Todd Ditchendorf’s Textmate bundle.

Using Git and Github

Watched this the other day — a good intro.

Screencasts or tutorials on:

• what git is, what github is
• installing git on Windows and Mac OS
• pulling Symphony rather than downloading a Zip
• contributing, forking, branches, pull requests, integration vs. master
• extensions

Articles/Tutorial ideas

These are not “documentation” (of the core functionality itself), more use cases for implementations:

• Creating an RSS feed
• AJAX with XML and JSON (convert XML to JSON)
• Building form controls with and without Form Controls
• Introduction to Events (insert/update, posted values, redirection)
• Showing Last.fm data and Twitter integration ideas
• Pagination (DS pagination, the Utility, next/previous links for single-articles)
• Master/Detail views
• View modes http://pastie.org/414188 (related to Master/Detail above)
• Dates (the Date field, syntax, filtering, date formatting Utility)
• Recursive XSLT (simple example, more complex custom example
• apply-templates and call-template, when to use which
• Search-engine friendly URL parameters (URL Parameters, ?xyz to $url-xyz parameters, /name:value/ syntax)
• EXSLT (http://exslt.org/): what is it, when to use it; not fully supported in LibXML, list of supported functions?; importing namespaces, excluding prefixes; common examples (tokenize, node-set, date difference)

I’d love to see a full API reference, information about best practices and example extensions to encourage new developments.

Performance

I think there should be specific mention to performance:

• your XML should be lean: ideally your DS should only output the data you need to build your page view. Anything else is redundant.
• the implications of attaching many Data Sources for specific page “modes” and their redundancy otherwise. Can be tied to using the “required URL parameter” feature
• using the Profile view to monitor page load times and analyse slow Data Sources

I’d love to see a full API reference

The “API documentation” or “API reference” is thrown about quite a lot. Have we defined quite what this actually is? I’m never sure whether it refers to one, or all, of the following:

• A full list of all classes in the Symphon core? Not all of this is useful, particularly the private methods of these classes. (It would only be useful for bug-hunting so I see this as fairly redundant)
• A list of core classes relating to extension development. Things like EntryManager, ExtensionManager, FieldManager, the Database class, and documenting their public methods?
• How about the anatomy of these things specifically? For example all of the methods of a DataSource class. Or the methods of the Field class?
• The MVC style of the backend of content.{blah}.php pages in extensions with their Index and Action functions?

An extension example would be useful, but extensions can do so much how do you cover it all? Extensions can provide: Events, Data Sources, Fields, Text Formatters, and indeed content pages.

Additionally, have you any thoughts about how the API documentation would be presented? If it’s a full class reference, then this is a mammoth job since Symphony code is not commented. We’ve already discussed the possibility of using something like PHPDoc to automagically create documentation. This would need everyone to chip in to document the core code. But there would be additional work involved in explaining these also, with examples etc.

jQuery is a good example here. They have a text-based Documentation section covering the concepts, and an API section which you enter from a code perspective.

There was a good example extension in the old 1.7 wiki.

Concerning an API reference: I’m thinking of a list of variables and functions available in the different contexts (events, fields, text formatters, content pages …). Furthermore all helper classes should be explained (entry manager, section manager, database connections …)

Should also add to the list:

• Delegates: names, order and the contents of their $context

Amazing, Nick. Thanks.

The 1.7 Campfire API documentation is purely for building the structure of extensions (folder structure, delegates and building UI pages). So this is essentially the “Extension API”.

This doesn’t cover the “Manager” classes, and the methods of the Fields/Data Sources/Events classes, i.e. the core classes that Symphony uses.

I think perhaps the “Extension API” can be documented as the 1.7 example (using words and examples) but I think the “Manager” type classes could be more easily documented using a PHPDoc-esque syntax.

Thoughts?

@nickdunn Anything better than PHPDoc?

I’ve not used PHPDoc (or similar) before, but if this open to discussion and a viable direction then other suggestions are welcome.

I just ran the Symphony 2 code through the phpDocumentor tool with variable results. Obviously there are no comments yet but it built a class reference and each of the members and methods. Here’s a cropped example:

As you can see… not pretty. But I think phpDocumentor can output in an XML format which we could then parse with XSLT and format as we see fit. Commenting the whole source code with PHPDoc comments isn’t a small job, but if it can produce a decent class/file list then I think it would be worth it. We don’t need to go the whole way of adding authors and version numbers to files, but I can see the community being able to document each class and each of its private and public members/methods.

Bauhouse has done some work to document the classes either manually or with a script. This is the same sort of thing as what PHPDoc is creating now without comments.

Additionally yourheropaul has written a similar script to parse the classes and build a reference (although the script has gone AWOL).

But PHPDoc seems to be the standard, and we can write our own templates to display the output we want.

Core team what are your thoughts?

For reference the [Tutorial] Building Extensions & Events thread brings up some good ideas about documenting extension development.

Another thing that could be documented in the developer docs:

• Database structure: nothing too detailed, but an overview of the abstractions used describing the naming conventions for tables etc.

I just ran the Symphony 2 code through the phpDocumentor tool with variable results.

I would love to have a complete class/file list reference, even if it’ll be without fancy comments!

The consensus within the Symphony team is to go with PHPDoc, due to the format being an industry standard. A custom solution was discussed but since PHPDoc itself have a big following, resources on PHPDoc would be plentiful. Going with our own solution would mean we need to write documentation for the documenter, not pretty.

So going forward, we need to look at the XML output and how this can be tied to the Symphony website alongside the new documentation system currently being developed by Craig.

Unfortunately, phpDoc seems to be unable to produce XML on my machine. nickdunn, have you experienced the same?

Unfortunately, phpDoc seems to be unable to produce XML on my machine. nickdunn, have you experienced the same?

Yes indeed, I was unable to create the DocBook XML, but with some troubleshooting and help from their community I’m sure we can. Alternatively one of my colleagues has a partially completed parser written specifically for transforming into XML.

Introduction to Events (insert/update, posted values, redirection)

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.