Fidel Vanegas

Creating complex “tutorials” using a blogging platform such as wordpress …

Jan 18, 2011 Blog Stuff

I am going to take the opportunity to write about “Blogging Stuff” topic on my very first article on 2011. This time I have been trying to understand how to publish “Complex” tutorials using the “WordPress.org” platform and for that I mean something that goes beyond the scope of one single article or blog entry. Simple tutorials can be written entirely using one blog entry which is pretty convenient for the publisher but when the content of an subject matter is complex in nature (long text paragraphs, tons of pictures, examples, code snippets, videos and so on)  then the next logical step is to break the whole into small pieces that can be assimilated or explored easily by the intended audience and still be considered atomic (one complete thing).

So without a lot of research on the topic and mostly using empiric knowledge about how tutorials in general are structured, here it is an attempt to tackle just few of the issues that a good tutorial structure thrives to resolve.

Assumptions and guidelines:

• A “Complex tutorial” is a collection of articles, when viewed as a whole explains how to deal with a subject matter entirely. One individual article may not be considered complete by itself in the context of the whole tutorial.
• A “Table of Content” (TOC) page is required for gluing all top level “Sections” or individual articles with the whole tutorial and provides the correct or suggested exploration path for the intended user to follow.
• A “Section” is also a page that provides a similar gluing mechanism of a “TOC” but for a subset of the tutorial which needs to be consolidated. “Sections” on top of linking to “sub-sections” and articles they will always links back to “TOC” and to a top level “Section” if necessary.
• “Articles” that form the tutorial’s content are plain blog entries (not pages) and they include a part of the topic related to the subject matter of the given tutorial. “Articles” in the context of a tutorial are required to handle the tutorial’s exploration path from their unique point of navigation within the tutorial structure; This means that “Articles” will always link back to “TOC” and the top level “Section” they belong to. On top of that “Articles” should link to PREVIOUS and NEXT elements within their “Section” except for the “Article” in the section’s path that can link only to PREVIOUS direction.
• Finally, whenever an URL is linked towards an element within the tutorial content (TOC, Sections or pages) the new page should be open in the same window replacing the previous one. Any other external URL should be opened in a new window or tab within the Web browser so user can point to it as reference without losing sight of the original tutorial page.

Assumptions above are a pretty basic way to view a tutorial structure and certainly anyone else could imagine a lot of more things to add but for now these will be good enough to try and see how it can be done in a very rudimentary way (no coding involved) using “WordPress.org” platform.

The tutorial structure explained …

There are many ways to explain a proposed structure of something but the most effective at least for me always end up being in a form of a graph. But even the most self explanatory graphs need some explanation:

• Pages (TOC & Sections) highlighted in yellow boxes, Articles (Blog entries) in withe boxes.
• All arrows show some sort of URL linking within the tutorial elements.
  • Black Arrows show top down linking paths.
  • Dotted black arrows denote links back and forward to “TOC”.
  • Blue arrows establishes links back to a top section.
  • Green and red arrows exemplifies article’s traffic paths NEXT & PREVIOUS.

Yes, I know, the graph above is a mess of lines connecting with boxes and it is only a pretty basic example of the few assumptions we had established before. So Now you get the idea of how complex in terms of adding URL linkages (HTML anchors) between the elements of a tutorial are required to be taken care of. Breaking any of the elements in the link structure will damage our tutorial navigation premises and therefore would make our final readers feel lost and unhappy.

At this point you will be asking yourself, why even bother trying to understand this issue. well, the reason is that Blogging platforms are meant to manage and publish articles in a “date/time based” specific way which is not completely suitable for creating the “complex” type of tutorials we are talking about which are “Structure” based instead. So what we are trying to do here is to enforce the structure described above into a “date/time” based web publishing platform and all just for fun.

At the end we are expecting to gain the following:

• Be able to publish well organized and navigable tutorials using a solid “RDBMS” baked web publishing platform without writing a single line of code.
• Tutorials can be created in a free publishing form way; starting writing articles in any order regardless of their place in the structure and at any time without losing visibility within our blog system.
• If you have already a set of articles they can be easily arranged in a tutorial form regardless of the date/time they were written.
• Your readers will gain a lot since they will not need to be searching for specific articles, categories or tags scattered around your blog site or even pointing to other blog sites. There will be a single entry point to find all related articles of a subject matter.
• Many more things I can think of but I will leave that for your imagination.

Getting this tutorial structure implemented …

Now it is time to get our hands dirty. The examples below consider using “WordPress.org” blogging platform but the same thing can be deployed to any other platform available but just not showed here. As promised, not coding will be required.

1- Add a new “Tutorials” page to your blog landing page. Well, if you are like me I do have anything else but my HOME and ABOUT pages showing in my blog so I guess we would need for the first time to add some space to keep track of all those tutorials we are going to generate in the time to come. So adding a new top level page to our blog site might be the very first step. It is also not a super secret how to add a page to a wordpress blog site.
2- Add a new “Tutorial TOC” page. Now that we have a link to fullfill we should create our “tutorials” landining page that will be hosting our sol called “TOC” among other subject matter introduction that goes along with it. This is the same drill as creating a page in step above but this time put attention to set “Page Attributes” -> “Parent” to “Tutorials” instead of (no parent)
3- Add a “Article 0.1” blog entry. So far we have created the top level pages, now we will actually create a blog entry or “new post”. How to create a new post in wordpress is also pretty trivial. Add the content for your article and make sure to keep the URL handy for the next step.
Do not forget to add your very first Navigation table, usually at the bottom of the content. This time we have the required links to TOC or “Main Index” page as we are labeling it on this example.
After adding new “Article 0.1” post, is the time to go back to TOC page and add a link to this page so we complete the dual linking (back and forward) required by our spec 1.0. Make sure you remember to set “Target” as “Open link in the same window”.
4- Add “Section 1”  page. Sections as explained in our asumptions are not blog posts they are also pages similar to TOC page. The main trick here is to make sure this page “Parent” attribute is set to TOC page. It is also important to make sure we add our Navigation table at the bottom of the page including the expected links to TOC, Previous and Next.
5- Add “Articles of section 1” blog entries. The key hint at this stage is to make sure navigation table at the bottom of each page is set as expected. This is a pretty manual process, basically copy and paste from original article but changing URL links for “Previous” and “Next” anchors. Also do not forget to update “Section 1” page index list to point to each new post created and make sure “Next –>” in navigation table points to the first article in the section.
6- Add “Section 2” page. This is also a mechanicl step very similar to step 4 above. The hint here is to make sure its “Parent” page attribute is set to “TOC” page , add the list of elements of the section and the navigation table is adjusted to follow links as expected.
7- Add “Article 2.1” blog entry. Adding this new post is not different than the previous section ones the only difference is that navigation table “Next” link will point to a “Section” page instead of an article post. Do not forget to add links in “Section 2” index list after creating this new post.
8- Add “Section 2.2 and its article 2.2.1”. At this point we are getting into a very repetitive drills where we want to complete our target tutorial structure example including all its navigation links for each page or blog post created.Hint; Section 2.2 page should have as “Parent” page attribute its top level “Section 2”. As you have noticed by now this is possible to do but keeping track of the URL links and making sure the expected navigation structure complies is not a trivial task. Basically this steps creates a section within a section and its article inside it, so again key here is keeping navigation table links and its top level section index links accurate. Before going anywhere, do not forget to update all the links of TOC index to point back to each individual item in the tutorial. I know, this is herd work but needs to be done.

At this point, if you have been reading all this way you may want to give it a try to the actual “Live Demo” of this “Tutorial Structure Example 1.0” and wonder if you would still have any energy left to leave a comment or perhaps a send a correction if you had spotted an error from the demo navigation and links.

Future Work

The example presented in this tutorial demo require a lot of manual settings to make sure all links are set properly so one definitive enhancement would be to create a WordPress Plug-in to define, manage and enforce the tutorial linking structure as well as to automate the way navigation controls are set to each page or blog entry.

In another different effort type, this approach can be used as a template for a web application that is entirely written to produce, publish and manage tutorials instead of relying on a blog platform.The idea would be to make tutorials creation and maintenance pretty easy so the tutorial creator just need to come up and start pouring articles into the dynamically defined tutorial structure where all links are always kept aligned and never broken.

I will keep dreaming at this point. If I would need to find a name for a tutorial platform application I would think of “Tlog.com” or something like that. Well, thinking more seriously it could be something like “TutorsPress.com”. Anyhow I will let this decision to the one who comes and implement something like this.