Symphony Documentation Site
This is an open discussion with 27 replies, filed under General.
Search
I think all three could work; it depends how you would want to manage/edit/update the content after that.
I would think github would allow you to keep better revisions/updates when compared to using frontend submissions; also this would allow preview prior to submissions as we'd technically have to pull the repo & ideally preview everything before.
Wiki; might work as well; especially if we're looking at the community to keep adding/adjusting/improving the tutorials.
Yes, wiki and github options seem better as they provide a workflow for editing and approval. It's hard to create "wiki-like" behavior in Symphony.
I forgot to mention, Jonas Downey has kindly donated his old Symphony articles from his old website to us to do with as we please.
That's awesome. Thanks, Jonas!
I would keep in mind the fact contributors shouldn’t be discouraged from contributing to the writing of the documentation by the idea of having to learn a completely new system.
So I would consider also the level of acquaintance with the way to contribute collaborators could have, when it should be chosen.
From this point of view GitHub seems better than the other twos.
I’d prefer not to rely on a native Symphony front end form submission for the reasons @gunglien and @TheJester12 wrote: it seems as we would be forced to reinvent the wheel.
My apologies to everyone about letting this discussion lapse. Life happened. A car accident, illnesses, academic schedules, etc.
So, we're getting to a final release for Symphony 2.3.3. It sounds like GitHub would be the way to go for maintaining the documentation. @theBigMandarino suggested (in an email) that we should do some research into documentation for other projects to find out how they are handling their documentation.
I've been taking some courses on leadership. Obviously, I've been doing a poor job of it with my Symphony efforts. I've decided to take a break from the courses and start putting the learning into practice here. Hopefully, it's not too little, too late to get some momentum going again.
It might be a good start to adapt Craig Zheng's Symphony book into a format like the O'Reilly book, Learning JavaScript Design Patterns.
Create an account or sign in to comment.
@theBigMandarino, thank you for your detailed comments. I think you're right that there are some excellent resources in the forum that just gets buried over time. It will be great to dig these up as well as the gists and other gems that exist in other places and provide a home where they can all live.
@brendo, those tutorials will be excellent places to start.
@Pat, yes, we definitely need examples of how to create extensions.
A Home for Documentation
Perhaps the best way to tackle these things is the way anything gets done: one thing at a time. So, here's one thing: I'm excited to say that we have a subdomain set up for the documentation:
http://docs.getsymphony.com/
But, don't get too excited, yet. It's just a placeholder for now. It just links back to the existing site. You can navigate to
/docs/
and click through the main navigation to see that there are empty pages waiting for content. But I don't want to create any links for Google to follow quite yet.Documentation as Collaboration
At the same time, I would like to make this process as collaborative as possible, so we don't necessarily have to wait for someone to post something to the site. I was thinking that it could be as easy as submitting a pull request on GitHub to be able to add something to the documentation. Of course, we would still want some leaders for the project to have some level of editorial control.
I am currently using the
docs
branch of thehtml
repository for the community site. Why, you ask? Well, I started using thedocs
repository to build the Documentation site with Wadoo, created by Marco Sampellegrini (@alpacaaa). But, I was thinking that even that might be too complex for what we're trying to do here.At any rate, I just wanted to open up the discussion on what would work best for the people who would like to contribute. And that's just me assuming that everyone agrees that this is too much work for just one person. So, the question is, what would be the easiest way for everyone to contribute?
Any other ideas?