Agreeing a content structure

[johnpuddephatt]

The documentation needs a content structure. This will help to ensure:

• the finished documentation meets the needs of symphony users
• it is easy for community members to contribute to
• we have a way to track progress as pages/sections are completed

Usefully, some content structures have already been proposed, both in the Google Drive Factory notes, and here on Github.

The content structure should define:

1. The top-level content 'categories' that give structure to the documentation (e.g. tutorials)
2. The pages that will populate these categories (will evolve over time, but initial list will be useful)
3. The metadata ('front matter', in Jekyll terms) that should be included with each page (e.g. article summary, keywords)

1 & 3 can be tackled immediately, while 2 depends heavily on 1.

1. Top-level content categories

These will form the primary navigation. Each category should have a clear description so that its purpose is easily understood by both readers and contributors – I would argue this isn't the case with the current documentation, as the difference between 'guides' and 'tutorials' is subtle, especially for beginners.

The categories proposed by @designermonkey are (or were):

• Installation & Setup
• Concepts (sections, pages, data sources etc.)
• Releases (notes plus download links)
• Tutorials
• Articles
• Screencasts & videos
• Developing symphony

I think this is good, but would like to propose some changes which I think simplify things a little bit:

• Landing page (introduction to the documentation, explanation of how to contribute etc.)
• Getting started (quick introduction to Symphony, installation, setup)
• Concepts
• Guides (with content split under subcategories of tutorials, articles, videos, developing symphony)
• Releases

  3. Article front matter

I propose we capture the following front matter for each page on the documentation site:

• ID
• Headline/title
• Abstract / short summary
• Layout

I'm presuming that additional meta data like author, date updated etc. are unnecessary as this information a) isn't important on the documentation site and b) will be captured by GitHub. I'm also presuming we don't need to capture keywords / tags? A bit of research shows that a jQuery-driven headline search function within Jekyll is quite feasible, adapting this so it's keyword driven is an option but perhaps it's more simple just to encourage well keyword-ed page titles?

Feedback welcomed with open arms. I realise I have a let less experience with Symphony than most of the people around here, so input is essential.

Next steps towards agreeing a content structure:

• [ ] Confirm a top level structure and article front matter based on feedback
• [ ] Draft then confirm full content hierarchy
• [ ] Create finalised content structure (store on wiki?)

[nitriques]

@johnpuddephatt you're missing a space between the two square brackets to make the checkbox works :smile:

[johnpuddephatt]

Oops. Thanks. Fixed!

[nitriques]

:sweat_smile:

[johnpuddephatt]

There was a lengthy discussion about the structure of the documentation site a while ago which I'd missed. Roughly summarised it goes something like this:

• Support for the idea of merging tutorials/articles/guides under one parent category
• Suggestion that the distinction be removed between tutorials/guides etc, instead splitting things out by subject. While there is a distinction between a guide (theoretical) and a tutorial (practical)
• Suggestion to structure the docs site with a clear progression from beginner to developer:
  • Install (releases, requirements, setup, concepts)
  • Build (guides, tutorials, articles, screencasts, videos)
  • Extend (extensions and extension development)
  • Develop (API and core development)
• Suggestion to make information navigable/presentable in different groupings/orders e.g. alphabetical, by category, etc.
• Suggestion that the docs site should just be "documentation" – that tutorials/guides/etc should be a part of the community site.
• Detour into discussions about gamification etc.
• Suggestion that the basic structure should revolve around concepts and then tutorials which show how concepts fit together.

A lot of suggestions, but no real consensus. My views remain much the same, but it's worth adding:

• I agree that the subject is the most important factor when a user is seeking information. Whichever of guide or tutorial is most suitable should then provided to address said subject. When I have a problem, I want to fix it. I don't want to have to first decide whether it's a guide or a tutorial I'm after.
• I really like the idea of concepts being seen as the building blocks for tutorials/articles/etc.

[tachyondecay]

I like your simplified structure, John. I’d add a top-level category called Community or Meta or something, where we can maintain the pages that are about the Symphony project itself, i.e.:

• where to get help—forums, IRC (though I tend to be all alone there these days), other sites that might have Symphony tutorials
• how to contribute to the docs
• how to contribute to Symphony itself
• links to non-Symphony things that might be relevant

[johnpuddephatt]

Excellent, thanks for the input :) Your suggestions tie in nicely with what's being said over in #5.

[bernardodiasc]

Just for the record, in Documentation site layout we have a main navigation (horizontal):

And the list of pages splitted by categories (vertical):

If this 3 hierarchy levels are not enough we can still split in pagination (paged pages would not be listed in the nav). But I think it is enough.

[tachyondecay]

I concur that those levels should be sufficient. I’m generally against pagination unless there are very compelling reasons to introduce it (and I see none here); it’s artificial and annoying to use and to keep organized.

[johnpuddephatt]

I’m generally against pagination :+1:

The proposal made by @designermonkey suggested using subpages, linked to from within a page but not appearing in the site navigation.

I think this would/should only be done sparingly, but could be a useful solution in certain cases. For example, it would mean that the page Advanced Setups under Getting Started would include links to specific pages about setting up on different web servers, rather than including (potentially lengthy) information about each setup inline.

I'm open to other opinions on this, however.

[tachyondecay]

The proposal made by @designermonkey suggested using subpages, linked to from within a page but not appearing in the site navigation.

I’m all in favour of subpages when it makes sense to nest useful but not critical information. By pagination I mean splitting a single, long article into multiple pages.

[jonmifsud]

@tachyondecay as far as I am aware SEO practices now seem to indicate that long articles are better than splitting into multiple pages (also easier to implement) maybe for the very long ones it might make sense to have anchor links to jump down the article rather than paginate.

[bernardodiasc]

@jonmifsud have you seen the tutorial I wrote? Is only 1 page, very long one. I like it, but not sure the efficiency of it.

[tachyondecay]

maybe for the very long ones it might make sense to have anchor links to jump down the article rather than paginate.

That’s a good idea. We can look into generating a table of contents and maybe stick it to the side of the page on larger widths so that it’s easily accessed at any point in the article.

[johnpuddephatt]

One option would be to auto-generate a table of contents for each page using jQuery. e.g. http://projects.jga.me/toc/#toc2. I’ve used something similar on an intranet site with many contributors and it worked well. Contributors just inserted headings into the document as they would anyway and the rest was taken care of automatically.

Edit: The Guardian's implementation of a table of contents is pretty interesting. It's static initially then fixed when scrolled past. I don't think this is something we should be looking to make any sort of decision on until content is created/populated, but it's still useful to collate examples.

[bernardodiasc]

Please dont worry about TOC now.

Also, Gettint started page must be the landing page.

[tachyondecay]

Also, Gettint started page must be the landing page.

Why?

[johnpuddephatt]

While I think Getting Started could be the landing page, I think it's by no means a given.

With the structures that have been proposed so far, we're looking at a site that goes beyond a narrowly defined documentation site, because we're looking to include guides/tutorials etc.

Because of this, it might be beneficial for the landing page to communicate what the different sections of the site are.

Design-wise I think it's a poor example, but the Symfony documentation uses its landing page to explain its sections quite well, e.g.:

The Symfony Cookbook – A collection of tutorials explaining how to solve the most recurrent problems faced by Symfony developers.

[tachyondecay]

Because of this, it might be beneficial for the landing page to communicate what the different sections of the site are.

That was my thought as well. A link to the Getting Started section should definitely be prominent on the landing page. However, because not everyone is going to be visiting the docs looking to "get started," the landing page should be more of a portal to the entire documentation site.

[bernardodiasc]

So the landingpage is the guide?

And getting started will be usefull only for newcomers, not to get started on docs as a guidance, instead, installation stuff.

[johnpuddephatt]

Getting started is only a provisional title, but it refers to getting started with Symphony.

[tachyondecay]

I've thrown together a wiki page where we can formalize this structure while we discuss it here. I'm really interested in getting this hammered out so we can start organizing and revising existing content and adding placeholders where we think new stuff needs to go. Please edit the page if you can clarify anything, or to reflect changes as we continue to discuss it in this issue.

Maybe someone could create an equivalent page describing the front matter for a typical page? I'm clear on what title and description do but am not clear on weight, and it would be helpful to have a page that formalizes when we need to use a different layout or whatnot.

[bernardodiasc]

Here it go my propose:

Landing page

This is the guide. As a user I'll open docs.getsymphony.com looking for something to learn. Here I locate the guidance for my kind of need. Each guide will shortly explain the path using links to other pages for further instructions. This will need to be a bit more succint comparing to the http://www.getsymphony.com/learn/beginners/. In other words, less text, more links for internal pages. We need to be very objective in the guidance to became successful.

Getting started

From https://github.com/symphonycms/symphony-2/blob/master/README.markdown

As we discussed, this is the section for readers that want to install, update, etc. I think we can change the name of the section to something like "Installation" or "Setup". Suggestions?

Concepts

From http://www.getsymphony.com/learn/concepts/

Sections with childs will have a folder, is dont have child will be a single file. Concepts index will list all concepts grouped with title and short description, click on title will redirect to the concept page.

Internal pages will have the same grouped list in the sidebar, only with the title.

• Sections
  • Fields
  • Entries
• Pages
  • Templates
  • Parameters
  • Page Parameters
• URL Parameters
• Data Sources
  • Filters
  • Output
  • Output Parameters
  • Datasource Chaining
• Events
  • Filters
• Utilities
• Authors
• Preferences
• Extensions
  • Delegates
• Devkits

Articles

The Article index page will have a list of all articles sorted by weight. Each item with title and link, and short description.

Articles are single pages, the internal pages will have the list sorted by weight in the sidebar.

Tutorials

Tutorials are almost the same as Articles, but some can be a collection of pages. If its a collection, the tutorial will have own folder. Otherwise a single file in the tutorials root folder.

Tutorials index looks like articles, but its sorted by date. Screencasts will be single pages here.

I'm still not sure if Articles and Tutorials are not the same thing. Maybe or meybe not. Suggestions?

Contributing

List of single pages. The index of this section will explain the open source ecosystem of Symphony in short and link to internal pages for further information.

In this section we'll have developer api, styleguide, contribution instructions, release notes, etc.

---

Please make suggestions. Let's define this so we can actually start work in the content. I had sent changes with placeholder files and new layouts, to better visualization of this. Please don't worry, everything can be changed once we agree on the structure.

---

Well, this was what I had in mind. But to be honest I loved this suggestion:

• Install (releases, requirements, setup, concepts)
• Build (guides, tutorials, articles, screencasts, videos)
• Extend (extensions and extension development)
• Develop (API and core development)

[bernardodiasc]

@tachyondecay cool, just saw your comment. let's move to wiki so. :)

[bernardodiasc]

@tachyondecay readed the wiki. looks good. IMHO we can use what you proposed. I understand the term "guide" a bit different, but its a tricky word. works nice to be the general name of the section the contain all material for learning.

[bernardodiasc]

@johnpuddephatt soon you share your thoughts and everyone agree, we start the awesomeness! :)

[johnpuddephatt]

great stuff! This is nice and compact which I think is exactly what we need to be aiming for initially.

I'm busy today, but one thought that's been at the back of my mind is how/when to seek wider input from the Symphony community. Obviously our discussions have been public but that's not the same as them being inclusive, as I wouldn't be confident all members of the core team are even aware of the docs.getsymphony.com repo yet! My initial thoughts:

• We should invite all contributors of the symphonycms/symphonists organisations to input on the content hierarchy that's been put together in the wiki (potential problem here is that the changes wouldn't be tracked, so could get messy?)
• We should wait until the Getting started, Concepts, Community and Releases sections are populated before publicising the site on the getsymphony.com forum and encouraging feedback/contributions for the guides section

These are just initial thoughts and as such I'm completely open to other ideas!

[bernardodiasc]

@johnpuddephatt we already have the community and core developers bless to take decisions about this project. If we open for more discussion we'll not end this, never. I'm saying this because what we are doing is part of an old goal, talking about years old.

My suggestion is: if you agree with what @tachyondecay proposed, and I had already agreed too, we can start building the placeholders and writing/migrating all content.

After we get all pages with the proper content, we'll make the redirectioning to docs.getsymphony.com and then we launch in the forum and blog on getsymphony.com.

I'm confident in the good decisions of this little commission. Once the project becomes public others will be able to contribute following the guidelines we defined here. :)

[tachyondecay]

(potential problem here is that the changes wouldn't be tracked, so could get messy?)

Wiki changes are tracked. Every wiki is actually a Git repo in disguise! We are all Batman.

I agree with what Bernardo said above. It’s obvious from the amount of existing discussions that you found that the problem has been "too much talk." Anyone else in the Symphony organization is welcome to chime in at any time—but if they were going to do it, they would have done it already. We’re the ones who have, so far, chosen to make this our priority.

[brendo]

Anyone else in the Symphony organization is welcome to chime in at any time—but if they were going to do it, they would have done it already. We’re the ones who have, so far, chosen to make this our priority.

Just to chime in, Ben's point above is extremely valid and I urge you to press forward with the momentum you have built up. It's far easier to iterate on solid ground than with ideas. Don't fear getting it wrong. It's all digital and can be changed. The hardest step is the first one :)

[tachyondecay]

I’ve merged some work I did in a separate branch into gh-pages, and then I moved content and placeholders around to bring it in line with our structure. I’m assuming the docs directory is more of a holding-area for existing documentation while we get everything organized.

As far as workflow goes, rather than branching for everything, for now I’m in favour of making changes directly on the gh-pages branch and pushing often. That way we can all keep up to date on what everyone else is modifying, so hopefully we won’t overwrite too many things or duplicate our efforts.

The nice thing about documentation is that it doesn’t have to pass "build tests," so at this stage of the game, we don’t have to worry about that branch being "clean." If we make mistakes, we can revert.

If you think you need to do something more major, like moving or changing an entire section, then that would cause for branching and opening a PR so we can see how that will affect everything.

[johnpuddephatt]

:+1:

I’m assuming the docs directory is more of a holding-area for existing documentation

This makes perfect sense to me.

[johnpuddephatt]

if they were going to do it, they would have done it already

Only if 'they' were aware that new work is happening! I'm not suggesting we down tools and sit and wait for approval from each and every person involved with Symphony, just that it would be good to make sure that members of the symphonycms/symphonists organisations are aware and know their input is welcomed – which I absolutely think it should be. If people feel that this is already the case (at least insofar as 'active' community members are concerned), then obviously my concerns are unjustified.

I'm confident in the good decisions of this little commission.

Me too, and I'm not suggesting that we shouldn't take the initiative here, I just don't think doing so is incompatible with ensuring our efforts are being communicated.

[tachyondecay]

Sorry, what I meant by it is the creation of documentation rather than sharing their opinions. The lack of momentum from the previous plethora of doc-related discussion is evidence that creating documentation just isn’t a priority for most members of the Symphony organization. If it were, we wouldn’t be here, doing this right now. :) And that’s fair—I don’t blame anyone for that. My point is merely that I’m doubtful you’ll find a lot of Symphonians are going to be popping in here to pitch in, at least not at first. There have been so many discussions about documentation in the past that it has kind of become white noise at this point. Until we actually make good on our intentions, we’re “yet another doc effort.” ;)

My hope is that once we’ve gotten this off the ground, then not only will this benefit new users, but existing members of the community will find the barrier to contributing documentation much lower. Once we’ve gotten to that point, then we’ll start seeing a lot more regular input.

[bernardodiasc]

Hey team, if we agreed the content structure we should close this issue to avoid more buzz and more than this, divide and conquer!

• Please create an issue describing exactly what are you working on, assing that issue to you and be responsible to the success of that task. You can ask for help or offer help for sure, this is more about dont duplicate efforts and maintain good communication. Sounds good?

Cheers!

[bernardodiasc]

can we think in a place to include a complete walk-through? something like proposed here https://github.com/symphonycms/wg/wiki/Docs-Contents

not suggesting to use this as the content structure, no, instead, have a place in our content structure that covers everything step-by-step in a progressive way. mostly linking to other pages, dont need to be redundant.

what do you think?

[bernardodiasc]

ah, we will use the book?

[tachyondecay]

ah, we will use the book?

I think we could definitely adapt the book. It was unfinished and apparently has outdated references to Symphony 3.0, so it will need revision.

can we think in a place to include a complete walk-through?

My goal right now is to offer the reader a number of appropriate options at the end of each walkthrough based on what they might likely want to do next.

So, for example, at the end of the Installation doc, I offer the option of touring the example workspace (which I will have to write) or trying the Hello World! tutorial (which we can port from the Symphony website). Which one they choose is going to depend on 1) whether they installed the example workspace and 2) what they are in the mood to do. I’ll also add a link to installing extensions once I've got that doc up.

I think there are better ways to link together the various pages than having a progressive walkthrough page—but, I’m not against the idea.