Symphony Documentation Site
This is an open discussion with 27 replies, filed under General.
Search
Hi Stephen,
As a light to middleweight dev, I find myself referring to the docs quite a bit to double check what I'm coding is correct.
I do find links to unfinished parts of the documentation frustrating dead ends to classes I need to refer to.. al in all the docs are very clear but sometimes a real use case for certain functions would come in handy. There are a few nested classes which do get confusing to grasp where they fit in using a categorized structure.. and I wonder whether a nested approach to explain how classes refer to each other may be beneficial to newcomers to the API.
Just my 2 cents.
@moonoo2, thanks for the feedback. When you talk about "frustrating dead ends," are you referring to the non-forthcoming "forthcoming" documentation mentioned in the Developer's Guide?
Can you give some examples of what you mean by nested classes in the API (keeping in mind that I'm a pretty lightweight dev myself when it comes to the API)?
More examples would be great. While the Wordpress Codex isn't perfect, it provides 2-5 examples of every function. These just show basic usage and formatting that the code might use, or may include the most oft-requested pieces of code or questions that come up.
Some video tutorials might be nice as well.
@TheJester12, so you're talking about snippets of XSLT, when talking about templating? Or any bits of code, whether it be HTML, CSS, JavaScript, PHP or XSLT?
Video tutorials would definitely be nice.
I also find examples of actual code in technical documentation make things a lot easier for me to understand. It's one thing to see a list of parameters; it's another to see an example of them actually being used. Maybe an example-inclusive approach could be used for Next's documentation?
Examples (for me) would encompass; How to use the SectionManager
, the ExtensionManager
etc, how to use the Navigation Datasource
, what the xml
looks like for the core fields etc.
Loads of tutorials for simple steps would be grand too.
The 'forthcoming' docs are a real embarrassment too as they've been there for over three years now.
Obv, you know I'm on board to help out, as we've discussed this privately.
@bauhouse Yeh it's the forthcoming stuff that got to me. More actual use case code examples is what I was getting at as well.
In terms of the nested classes comment, I think what I mean is a more visual way of denoting how a class is an extension of a parent class.. sometimes I have to jump around 3 or 4 functions to find the parent class is what I was after. I'll see if I can dig out an example today.
Brendan has (buried between all these release notes) multiple very helpful Gists to explain more advanced stuff for extension developers. How to use certain functionality, how to create custom events...
That's the things developers need to know and that should be easily found on the official documentation site.
Other examples would be, how do I create a custom datasource and return data as proper XML? How do I query the database? How do I correctly (with security in mind) use the managers or database class in my custom datasources, events or extensions? What's the right way to work with Sessions or Caches in Symphony? Stuff like this...
Yes, @DavidOliver said what I meant. While XSL snippets would be nice, I was primarily referring to the API documentation. Examples of PHP code make more sense than only lists of parameters and stuff.
That said, what @jensscherbl also would be nice. Stuff that might be simple to some developers here, but things that guys like me have trouble with:
- Customizing a datasource
- Customizing an event
- Get a list of entries from the database, spit them out as XML
- Basics of plugin development
Thanks, everyone.
Yesterday, Allen set up the docs subdomain, so we can start playing around with Symphony Factory and organizing a way forward for the Documentation site. I'm pulling data from the existing site, and it would be good to bring all the documentation together into some form that we can easily repurpose.
One thought was to use Craig Zheng's Text Upload field extension. It looks like version 0.4 should work with the latest version of Symphony. Can anyone who has been using this extension confirm this?
That'd be interesting. Also interesting might be some kind of integration with github gists... That may be more easily editable by multiple people?
Yesterday, Allen set up the docs subdomain, so we can start playing around with Symphony Factory and organizing a way forward for the Documentation site. I'm pulling data from the existing site, and it would be good to bring all the documentation together into some form that we can easily repurpose.
Maybe a stupid question, but is this happening in public or somewhere local? Where can we view the progress and contribute?
Well, I'm still trying to figure out the best way forward. I started with xsltproc as a static site generator. Marco, Simone and Andrea suggested using Wadoo, so I implemented that. But, then I was hoping to get Factory implemented in Symphony. So Factory has been integrated into three different methodologies.
Now, we're considering Symphony + the Text Upload extension.
For now, I'm sticking to what I know, which will allow me to experiment with static HTML without having to worry about Symphony sections and fields and extension dependencies yet.
But I haven't got that far. I grabbed the XML for the documentation from this site and saved them as flat files. You will be able to view my experiments in the docs branch of the HTML repo. But, I don't want to say we're ready to collaborate until we've figured out what will work best to allow the community to easily maintain the docs.
If you have some good ideas, let us know.
Now, we're considering Symphony + the Text Upload extension.
If this doesn't work, let me know and I'll make the relevant updates to make it work :)
@brendo @bauhouse: I remember having a pretty serious bug with this where it would clear files, so I had to avoid it. Can't remember the specifics unfortunately. I seem to remember I was using it with Order Entries to set load order, and if I modified the order and saved entry it would get blanked.
@s_e Thanks for the input there! Valuable before I really get stuck in with it.
@brendo, I need to discuss this with you and Stephen, I will email you later about an idea here.
Answering to the question “What works and what needs improvement?”, here’s the experience I had with and few thoughts on the documentation.
I start by saying I approached Symphony as a designer with a rather decent knowledge of HTML and CSS, a fair awareness of what XML is and some basics of Javascript, but totally unfamiliar with XSLT and XPath.
I’ve tried recollecting all the difficulties I have had while learning Symphony starting from scratch to identify what the pros and cons of the current documentation could be, so the point of view of the following considerations is from the eye of a used-to-be-or-at-least-i-hope-so newbie focused on creating by means of rather than for Symphony, so I’ll leave out the development of extensions area because—unfortunately—it’s out of my hands.
There are two main places where you can learn Symphony, that are the “Learn” section aka the documentation and the “Forum” of www.getsymphony.com.
The “Learn” section is the place to start with. The topics addressed in its “Tutorials” and “Articles” are complete, detailed and funny to follow—that is definitively a plus. Tutorials and articles offer both a very good general introduction to Symphony and detailed explanations related to specific subjects.
On the other hand the forum is the place where particular problems are addressed and solved by a very kind and friendly community (of course the forum it’s also a place for discussing or keeping up-to-date, but I’d consider it only as a learning resource in this context).
What I feel is missing at the moment is a place where topics not so general nor specific as the ones currently addressed in the “Learn” section (tutorials and articles) nor so particular as the ones addressed in the forum are collected.
To better explain my self: common patterns, best approaches and workflow optimizations can only be gathered indirectly by searching the forum.
The problem is that in the forum they’re scattered all around and it’s not so immediate to directly access them, since the forum is—by its very nature—oriented to solve particular problems by means of questions and answers: either you’re searching for the very same question which fueled the thread or it is probable you can miss them—especially if you’re a “freshman” (too many unread threads poured on you).
For example: recently searching the forum I stumbled upon this nice repository by John Porter which contains various templates, among which get.footer.xsl and get.header.xsl.
They’re rather small pieces of codes—simple ones if you know how to do them—but I remember it took me a while in the past to shape my templates this way because I reached such a solution only by trial and error and by inferring it from other not directly related topics.
When I found them I though that if I had the chance to discover them earlier—maybe in a super short article—my very first templates would have been surely better and less chaotic.
Another example could be the element. I was not aware of it before stumbling on it while searching the forum for a totally different matter, but I’d have surely made a good use of it in past projects. I think it’s a practice which should be introduced beforehand similarly to the ninja technique, so that you’re aware of its existence before you actually meet a dilemma which can be solved through it.
I’m aware the idea of documenting/suggesting common patterns is arguable due to the flexible nature of Symphony (there’s not only one good way to do things), but I think getting to know how something can be done allow you to customize it later at your taste.
One way to understand which topics should be collected and addressed could be looking at the forum: every once and then recurring questions come back.
For example: Nick Dunn has been frequently (and patiently) suggesting to write the line php_value display_errors 1
in the .htaccess in order to make users able to understand what’s going wrong. I think the reason why this hint has to be repeated so often is due to the fact it’s only present as an answer to particular questions. Writing a simple tutorial/article titled “Don’t panic!” giving few directions to narrow down an error when the screen goes blank could be a nice move.
Another improvement could be adding/referring to few concrete examples for certain concepts in “Concepts”: the section is definitively well written and complete, but sometimes I felt as I’d been able to grasp a concept even better by having a real use case added to its abstract explanation.
For example: the real use case of the GET parameters concept could be how you can rely on a GET parameter to build a pagination when multiple URL parameters are in use (also this one is a recurring question).
I think the data source chaining concept would benefit by having a real use case as well.
A notification sent to users when some new article/tutorial is published would be a really nice feature too: while writing this post I discovered few articles I didn’t notice before….
My very last observation is related to the partitioning of tutorials and articles by the categories beginners, users and developers. I understand its purpose but I think filtering tutorials and articles beforehand doesn’t allow users to have a clear overview of them. I’d let users filter them only after they’ve seen the overall picture, otherwise there’s the risk something could be lost.
I think we need to focus on a couple of key tutorials:
- Hello World (updating it for 2.3)
- Hello World Part 2 (something more complex, section creation/events, where to go for extensions etc.)
- Setting up your first Members site (Members + Symphony, bonus addon is Email integration)
- Datasource chaining with multiple parameters (we have no tutorials that talk about multiple parameters)
+1 for how to make an extension tutorial with different examples
Create an account or sign in to comment.
The plans for new Symphony website included a plan for the Symphony documentation.
As plans move ahead to complete the last releases of Symphony 2 before moving on to Symphony Next, it becomes a more urgent priority to create a documentation site that will serve the final version of Symphony 2.
The work that has gone into the existing Symphony tutorials, articles and API documentation has been fantastic. But the current documentation is showing its age, and there have been some gaps that need to be filled. So, as we work on redesigning the documentation with the Symphony Factory framework, it would be very helpful to hear about the experiences people have had with the existing documentation. What works and what needs improvement?
Also, if anyone would like to get involved in the documentation effort, please let us know.