Create Documentation site #10
Comments
|
I like the basic structure John proposed, but some time ago Stephen expressed his concerns about the compatibility of such a structure with the menu system of the Symphony Factory design. Regarding such a problem of compatibility, I’d like to take a step back first. I think the documentation will mainly address two kinds of users:
I don’t think the current menu system (Guides, Tutorials, Articles, Concepts, FAQ, API) is too much of a help for both the kinds, because it presents the pieces of documentation organized in categories rather than subjects. Dividing the various pieces of documentation in different categories depending on their nature for the sake of keeping the documentation tidy is a must, but I would not try presenting them divided in categories, because every label doesn’t tell directly what’s underneath it. Moreover pieces of documentation related to the same subjects can fall in different categories. In such a perspective I agree with @jenssherbl when he says it would be a good idea to consolidate Guides, Tutorials and Articles into a single section. What do you think about consolidating the pieces of documentation into a single section and organizing them by subjects rather than categories? Maybe we could create a more detailed index as a landing page rather than trying to fit everything in the few space available in the menu, so that we can give a clear overview of everything to viewers since the very start. I’d enjoyed going through the detailed structure John wrote because I had a clear overview of everything:
|
|
I quite like John's content structure as well. Similar to @jennsherbl, I wonder if the Articles section can be removed and just merged into the general site blog? I don't feel there is a strong enough difference between a Guide and a Tutorial, so happy for them to be merged. |
|
@designermonkey, I like the content structure proposal. It is very wordy for a main navigation for the docs site, but it works really well as an index, so @theBigMandarino, I think you're on to something with idea of a landing page:
Of course, keeping in mind that we are making this responsive as well. @theBigMandarino, what in your mind is the difference between a subject and a category? Can we divide things into steps:
Maybe it's too abstract, similar to what we already have. But it shows a progression from a beginner just getting started to someone who is getting familiar with the system and starting to build things to someone who wants to understand how to extend Symphony by first becoming familiar with which extensions are best for particular use cases and then by understanding how to adapt and develop new extensions. By then, people have graduated to the level of understanding the API and being able to contribute to core development. I think this would make a lot more sense than dividing things up by content type. In the same way that we want to bring all the content into a single stream for the community site, I think we should do something similar for the documentation. |
|
When I was starting to look at learning Laravel, I went through the docs one by one in order that they were listed. The same goes for Slim too, and I started to build up a knowledge of the product and it's purpose, I wasn't concerned with pitching myself into the docs as a beginner as they were structured into the actions I would need to perform to build up a project. The main focus in my structure is to start at the beginning and work my way through to more advanced concepts, while also nesting more advanced concepts related to the current one (that sounds weird reading it back). We need to remember that all this is, is a hierarchical structure of data, we can reference it in many ways; Using the structure I propose, using the simpler categorisation that @bauhouse suggests. Hierarchical structures are good for storing data and getting a top down list of steps to learn to get somewhere, but categories do lend themselves more to a quick reference of content. I reckon we should store it hierarchically, and attach categories, tags and other stuff to each entry to make it searchable and findable in other ways. We could even let the user choose how to access it by displaying both structures to them; A sort of live A/B split test on the site. With reference to the structure not fitting the design, I believe that it is the design that doesn't fit the structure. The community paid for the design, but it was completed without us having any real content awareness for the new sites, so I think it needs re-addressing now we have something to tweak. Remember though that the hierarchy is only navigable to two levels in structure, with other links in pages/articles to extra content:
for example:
I like the idea of having an overall index page, but wouldn't we anyway as a human navigable sitemap? |
|
@bauhouse, I think I picked up the wrong word using “category” (too generic), let’s use “form”, “shape” or “type” in place of “category”. In my eyes the difference between subject and form/shape/type can be inferred by the following example:
Presenting contents organized by subject rather than by form/shape/type seems more meaningful to me. I would still make a distinction among contents having a different form/shape/type, but I would keep it as a secondary/subordinate way to accessing contents. In such a prespective:
|
|
I think the simpler the better. not sure if I'm right but to me it seems that guides/tutorials/articles are more or less similar. It's just a matter of writing structure and possibly page-level styling differences(if any). However (also from my understanding) we want part of it to be collaborative, mainly guides/tutorials (possibly articles) whilst I guess blog-posts are intended more for the core-team/selected community members to provide updates. So that's where I would have separation especially as we're looking for contributors to help on guides/tutorials via github. The collaborative stuff would go into one part of the website; which can be browsed through tags/other taxonomies, as previously suggested. Whilst we're at it it might be cool to add a 'read' feature for these items, especially if a user is following a linear-path it helps him progress through the articles/tutorials. |
That is a cool idea! Especially if we tie it to their Symphony/Github account. |
|
Add to that: Earning Symphony kudos points or something. We all know Brendan Abbott wrote:
|
|
@designermonkey sounds interesting to work with a point system; but we have to be careful on how we award them. You wouldn't want people skimming through the site or posting just to earn points (which might potentially lead to jobs) As for the progress, I was thinking we could use something like http://imakewebthings.com/jquery-waypoints/ especially in multi-step processes where we would have long-pages. So a user would not just follow the read tutorials/guides but also know at what stage they last stopped. Usually setting up a Symphony Site (A-Z) in case of some tutorials takes more then a couple of minutes. |
|
If we're thinking of gamifying the process of learning about Symphony, then we could thinking about levels and pathways. This would require metadata for each content entry that gives context to the knowledge and skills prerequisites to best understand the information. Completion could "unlock" levels or branches of additional information: "Now that you know how to do this, you can try that." |
|
If we’re thinking of gamifying the learning process, an interesting source of inspiration for handling the “levelling up” could be Codecademy. |
|
Or Duolingo. Which really has stole my heart for weeks now. One potential
|
|
@brendo, what language are you learning? Hmm, Duolingo doesn't offer Mandarin. I wasn't thinking of blocking or obscuring content to people playing the game. Only directing people to content or learning pathways based on their current level of knowledge. Sort of a personalized "you might also be interested in..." or "related articles" feature. |
|
I just signed up for Duolingo for a quick look around. (I might as well learn some Italian, right @theBigMandarino. They don't appear to have Maltese, @jonmifsud.) That looks pretty cool! I'm imagining how that might work for Symphony. Instead of nouns and verbs, it would be concepts and workflows. I went to a grad presentation for Emily Carr University of Art + Design in Vancouver, and one of the industrial design students was presenting on a web project she had created as a replacement for antiquated systems that colleges and universities tend to use, like moodle and blackboard. I met with her after the presentations to find out more. Now that I will be teaching university students, I think it would be great to have access to a tool like this: http://www.youtube.com/watch?v=1G4mOoF_o8s. She's continuing on to do a Master of Education Technology degree. I'd like to see something like this built with Symphony. |
|
More inspiration for interactive visual learning: http://pcottle.github.io/learnGitBranching/?demo This really helped me when I was figuring out git. |
|
Oh god, it was more a flippant comment than anything, I think we need to actually stick with something simple and get it built. |
|
Haha, yeah totally. Some words on screen would do the job for now. :) Just to say that I'm happy to help out here too. I'm still learning a lot myself so I refer to the docs and search for snippets of info as I go so from that respect I can use myself as a good example of what I'd like to see in the docs. I've spent the weekend trying to catch up with all the conversations but I think I'm pretty on par now. By way of a few quick comments I agree that Articles & Guides present too much of a breakdown and only serve to confuse when most people will just want to understand the fundamentals (concepts) and then see some practical examples (tutorials). I'd look at it as Concepts (the actual reference material), and then Tutorials which aim to put the concepts together into a cohesive whole in a practical example. i.e. "Hello World", "Hello Symphony" etc. Obviously the API docs would have their own section too. That keeps it nice and simple and allows for a narrative approach. For the most part @designermonkey's structure looks about right. One thing I would say however is that because the docs are all about content for the time being would it not be simpler to just put things together as a collection of markdown files to make it easy to collaborate on? That way we don't confuse the building of the site with the content of the site. Content first, then apply design. As @designermonkey mentions, the site needs to adapt to the content and not the other way around so from there any tweaks can be made to accommodate. Just to clarify on the task at hand. Is it to directly just transfer the docs on the current site to the new site or is it to update them and add to them? |
That was the initial idea, and I hope still is. I was looking into the Text Upload field as a vehicle for this, in that we would have a repository on github which users can submit pull requests, issues etc, and have a copy of this repo local to the site which is incrementally pulled. The field allows any filesystem changes to be automatically mirrored into the database. This is the best option for us, and each section of the site would have this field pointing to a subfolder of the repository mirroring an agreed hierarchy for the content. Anyhoo, I digress... |
Well, this is the question isn't it. In all honesty, we need to take what we have and make it fit two things; 1) The new structure, 2) Symphony 2.3.3 That says clearly to me that we do indeed need to re-write what we have. I reckon the majority is there in one guise or another, especially when throwing Jonas' and my articles (read: article, ahem) into the mix. There are two repositories already on github that hold some content by some community members, so they are also in the mix. It's just a matter of co-ordinating what we have, what we need, our tone of voice, and then getting interested parties to write the content anew, using old content for reference. That's the difficult bit as no one ever wants to write docs. We've been trying for years now. |
|
So, trying to sum up the main points emerged so far. Up until now it seems the content of the Symphony Documentation site will be made up of three main sections:
Resources will gather all resources (guides/tutorials/articles) under a same roof and be structured according to John’s content structure (linear reading). Concepts and API will gather all Symphony definitions and work like a dictionary/encyclopaedia (random/casual reading), used as a reference by builders and developers and referred/linked to in all other resources. In general I’d suggest we should all agree upon some sort of general style guidelines for producing the docs, otherwise the result could be rather colorful. |
|
If I were to read Resources on a site, I would be thinking it contained code snippets, downloads etc. Resources is not the right choice IMO. Examples to look at before we start to define the structure (and examples I looked at when coming up with my proposal) are:
I really don't think we can over simplify it to those three words. |
|
WordPress!? I hope you cleaned your cookies before heading back to Symphony soil. :) To be honest when I think of "docs" I think of just the "documentation" rather than a complete learning suite. The Concepts, API, and maybe a few getting started tutorials (as mentioned above). I'm not sure if I'd think to ever go to docs.domain.com to start reading articles or even following screecasts etc. If that's the case then I'd either look to change the subdomain to something like "learn" or just merge that into the main site as it is at present. The key thing with "docs" is they're usually quite closely related to the core product so when the product gets updated so do the docs. Obviously learning resources like articles and screencasts will generally be more fixed so it will result in a mis-match over time. Docs would include a few other integral pieces of information including a brief preface/intro, server requirements, licence info, and release notes so I have all key core info but anything else starts to wonder out of "documentation" territory. If the docs are kept light and to the point then they can be a little easier to navigate and even update regularly with each release and can stay in the domain of the core contributors. Usually the learning resources (and marketing) of an application or framework are put together but the community in the form of external blog posts, articles, screencasts etc. Is it a good idea to be too controlling with insisting that it's all in one place? Reading through The Tao of Symphony this approach is almost in complete contrast:
The docs just need to reflect the latest core release. Keep them small, agile, and with a focus on clarity. With the fundamental knowledge and the instruments supplied trust in the community to supply the learning resources as these are generally a snapshot in time (a blog post isn't intended to change from the date of publish nor are things like screencasts. They will forever target a specific version but provide a learning resource none the less). I think anything else will be biting off more than an already stretched community can chew. I really can't see articles, guides, screencasts, etc ALL getting updated with each new release so I can already foresee a management nightmare when everything starts getting out of sync with different versions and no one wanting to update them all. The community isn't large enough for that nor should it be solely responsible. Keeping things simple and getting things done is what Symphony is all about. |
|
@designermonkey, I don’t like the word “resources” either, but I had to write something for referring the group of tutorials, guides and articles: resources seemed fine as a provisional name—it’s meant to be changed. Maybe “Docs” would have been a better choice, but it didn’t come to my mind when I wrote the comment! ;-) |
|
No problem, it's all for discussion :) I actually like the idea of figuring out what should be on what site as @ijy describes. |
|
Let's not forget that Craig Zheng did a tremendous amount of work on the Symphony book. (By the way, how do we get access to that old site? It's no longer accessible after switching servers.) He created it as a Google Doc, and I made it accessible to everyone as part of the Symphony Working Group repository on GitHub:
The Table of Contents for the Symphony Book gives a fantastic overview of the Symphony CMS project. There are a couple problems with the book content: it was written for what was going to be Symphony 3 and it was never completed. Ten chapters have been completed. That leaves half the book needing to be written (nine chapters), but three of those were meant to look at project case studies. The overall structure of the book looks something like this:
If we try to simplify the wording down to something that could be used as navigation, it could be (I separated API out from the other chapters in "Part 4"):
|
|
That sounds like a great starting point @bauhouse, it definitely makes sense to reuse some of @cz's work considering he has already put a lot of thought in the structure of that book. I don't mind Fundamentals, I think it's more guiding of 'start here', than Concepts. For the sake of progression, how do we actually start this? I've got a 3 hour plane ride in 2 days that I can use productivity :) |
|
Wow, it's a shame that book never managed to get finished. That would be a great learning resource in itself.
I'd say we need to:
Description:
With regards to Craig's excellent half-finished Symphony (the book), would it be better to keep that as a separate section? Maybe just as it was previously with it's own subdomain or section on the site? Again it just goes down to what is to be included. Docs being more of a quick reference in my mind whereas a book is an excellent in-depth learning resource. Similar to Code Bright the book, and the Laravel docs. Note that the Laravel docs are specific to a version and are updated with each version (four.laravel.com). A full learning suite will eventually comprise of different versions and features and muddy the waters. We should really keep versioned "docs" for Symphony going forward especially with the possibility of Next in mind. This is where I think there needs to be a division for ease of management & clarity of learning. |
|
Folks, let me know if there's anything you need from me here. My time's limited but I'm happy to be a sounding board if it's helpful. |
|
@cz, you mean beyond chapters 11 through 19 of the Symphony Book ;-) Thanks, Craig. It would be awesome to get your thoughts and input. By the way, do you have an ensemble kicking around for the book site (now that we no longer have access to that old server)? |
|
Happy to give input if you guys think it might be useful. What are the open questions? I do have that ensemble somewhere. Let me dig it up... |
|
@cz, There are a bunch of open questions. That would be awesome if you dig up the book ensemble. You might even be able to get some cash for that. Andrea Buran (@theBigMandarino) and Jonathan Mifsud (@jonmifsud) met with me last week in a Google+ Hangout to discuss the current state of development and documented things in a Google Doc which was translated into meeting notes on GitHub for transparency. We're putting together a list of questions that we still need to hash out. At the moment, things have been gathered into a Compendium document as a Google Doc. If anyone is interested in joining us, we have another Google+ Hangout event planned for July 27, 12:00 UTC. Just raise your hand here, and I'll figure out a way to invite you to the hangout (if there's room). |
|
Thanks to everyone who attended the meeting. Here are my notes: Working Group Meeting 27 July 2013Attending
Notes
|
|
Just letting you all know that August 4th is my sister's birthday and I won't know exactly how long the event might take. Given that it'll be Sunday evening 10 pm my end, I think I should be able to make it. |
|
Stephen just mailed us about this: August 4th is Max' second birthday so @johannahoerrmann and I won't be able to join the meeting. |
Is this in regular doc format or just text/markdown files gathered up in a folder?
So someone can submit a front-end form and upload a text/markdown formatted file? Does this automatically overwrite an existing entry? Is there version control at all? Is this just for Working Group members or the general publich? Will they need an account or just free form submissions? Has this been updated to work with the latest version of Symphony?
A combination vaccine for infectious human diseases?? |
I think this just refers to documents defining how the site is going to be built etc; for us to manage documentation for creating / updating workflows etc.
Maybe the name of extension is not very clear; we were thinking of having a git synch'd repo which is automatically pulled up and markdown changes are visible on the website. I haven't tried this mentioned extension, however seems like this was it's build scope. We'll be looking to see if it can do the trick; otherwise we'll look at alternatives. However we did agree that this data should be managed with github, so it will be easier for anyone to submit pull requests with new posts/modifications. |
|
Yeah I wrote Text Upload Field for exactly this kind of scenario. The content can change on either end—file system or Symphony UI—and the other will be updated (IIRC). Wasn't tested super thoroughly but I did use it for a project and it went well. |
|
stupid question... if we are planning to have this sync'd using git... I On 29 July 2013 16:03, craig zheng [email protected] wrote:
|
|
Yup, that's right. If the content is changed in the UI, it'll update the files but those would be overwritten by the next pull from git. |
|
Unless you used some nifty @designermonkey magic and wrote a script that automatically checked for changes in the local repo and pushed them back to github, however, the model we're discussing wouldn't have changes made in the UI. The content would only be edited in the repository. I would assume that once the sections are set up and pointing to the folder hierarchy, they would be hidden from the Publish view anyway. |
Develop a separate instance of Symphony based on the Symphony Network Ensemble to be used as the documentation site. Modify the page to match the proposed structure:
The text was updated successfully, but these errors were encountered: