A Direct Connection For Certification Content

While I have a fairly well-formed image in my head how the Creative Commons Certification system will flow, at times (many times) despite efforts to sketch and explain, I wonder if others do.

I will keep trying. And I think/hope it will be clearer as we roll out in the next month or two, more tangible prototypes (although it is floating around this site clearly visible).

What follows is… more sketches! And some what I think is cool new way to speed up the connection of the public content on this site with where it is being produced and edited in GitHub. Sit back and plug in.

The Development Side

In the early days of the web just mentioning “HTML” sent people scurrying away (say it know and they probably shrug). The same goes now trying to explain how we are using GitHub as the canonical source for the content — do not say “Markdown”!.

My own understanding and application of GitHub is pretty trivial compared to its capabilities.

So for starters let’s say that there is little reason for anyone using or even deploying what we are developing to even touch much less look at GitHub. But it is there for the intrepid. We now have four separate GitHub “repos”– for the “Core” content, plus ones for the Library, Education, and Government specialty certificates.

These are not terribly exciting, they represent the content in a purely structural form that includes headings, links, images, lists. The content is in Markdown, a much flavor of HTML.

Main entry to the GitHub repo for the Library Certification

One will find a common structure in each, this is a bit of the Library Certification with a Module that is from the Core content (modules that will be part of all Certifications):

Cover / Splash page (index.md)
- Overview (overview/index.md)
- Delivery Format (details/index.md)
- Contents (contents/index.md)
  - Module Intro e.g. Copyight (contents/copyright/index.md)
    - Unit e.g. Copyright Basics (contents/copyright/basics.md)
    - Unit e.g. Scope of Public Domain (contents/copyright/public-domain.md)
    - Unit e.g. Exceptions & Limitations of Copyright (contents/copyright/exceptions-limitations.md)

We are already seeing that the Library Certification decided on a different order for the units in some of the modules, this is done by simply reordering the list of units in the main contents.

This outline structure maps directly to a parallel one when the content is moved into a WordPress site (we are using the JetPack plugin to be able to render Markdown content when published).

Cover / Splash page (certificates.creativecommons.org/lib/)
- Overview (certificates.creativecommons.org/lib/overview/)
- Delivery Format (certificates.creativecommons.org/lib/details/)
- Contents (certificates.creativecommons.org/lib/contents/)
  - Module Intro e.g. Copyight (certificates.creativecommons.org/lib/contents/copyright/)
    - Unit e.g. Copyright Basics (certificates.creativecommons.org/lib/contents/copyright/basics)
    - Unit e.g. Scope of Public Domain (certificates.creativecommons.org/lib/contents/copyright/public-domain)
    - Unit e.g. Exceptions & Limitations of Copyright (certificates.creativecommons.org/lib/contents/copyright/exceptions-limitations)

All of the content on those WordPress pages are the same Markdown content from the GitHub source– with a small bit of help from a small plugin that makes these adjustments (this is getting into the nuts and bolts of code, feel free to let your eyes go glossy):

The Markdown header line is removed (since WordPress has its own title field)
The embedded image URLs need to be re-written from their GitHub source which do not render as a URL direct to the image. For example this URL that works on GitHub to display it on a page as an image actually points to a URL of the GitHub page that references the image. The helper plugin rewrites the image URLs to the public GitHub pages version of the same image so
https://github.com/creativecommons/cc-cert-core/blob/master/images/copyright/vvgvlh1d10u-slava-bowman.jpg

becomes

https://creativecommons.github.io/cc-cert-core/images/copyright/vvgvlh1d10u-slava-bowman.jpg
All link references to contents/some-module/index.md or contents/some-module/some-unit.md are rewritten to contents/some-module/ and contents/some-module/some-unit/

As yet another sketched idea, here is how I see the development side (where we are working now) for the certification content:

Connecting the Github content source with WordPress

Our team and other contributors draft a unit in a Google Doc; when it is close enough to ready, meaning all of the parts are at least present, I convert it to Markdown and put in Github where further edits/refinements are done.

Until this time, the movement from GitHub to WordPress was a “grab and go”..

The New Direct Connection

How this was done before was old school sneakernet – I would copy the full Markdown content, paste over what was in WordPress, and the above conversions are done when the page is saved. At first, working on the Core certificate content, it was not too much work to do, but now that we are building at the three specialty certificates, each that includes most of the Core modules and units, it was looking inefficient.

I had looked briefly at the WordPress GitHub Sync plugin, but I am not looking to have two way sync; we want the source in GitHub to be the ultimate one.

Last week I started looking at simpler approaches, a way to call GitHub via it’s API and update the content directly to wordpress. I got it working fairly easily using a post from DobsonDev on API Calls with cURL. While you can do this without any authentication, it is rate limited, as I found on my test machine when an errant WordPress endless loop maxed out the number of requests I was allowed. So I added simple authentication for testing.

Each content page in the certification has what WordPress calls “custom fields” or meta data for the page. I use one field to describe what kind of page it is in the hierarchy shown above. A second field contains the URL for the content source in GitHub:

Custom fields indicate the type of content (“unit”) and the URL for the content in GitHub.

Eventually this will be edited via a more typical user interface (drop down menu and a labeled URL field). This is info set up once on the back end, people editing the content do not need to deal with it.

Mostly for my colleagues, this is how it works… you make changes / edits to the GitHub source page, say for the new Remixing Differently Licensed Works Unit, perhaps added a few more resources or changing the wording of the prompt for the social participation portion. You save and commit the changes.

Nothing changes on the WordPress site, it’s not a sync-ed connected. But all you would need to do is to edit the page and click the Update button. All of the content will be fetched from GitHub and processed for display as described above.

The Production Environment

Everything I described above, if anybody is still reading this, is behind the public scenes. The WordPress site described above is meant to be a transfer from the Markdown content to more typical WordPress HTML content. After converting all of the remote images to local media library ones, the certification content from the Markdown source sites will be exported as standard WordPress XML, and re-imported into new WordPress sites.

This will be the public facing sites, and the export XML files the ones we can make available to organizations that want to offer and customize their own. The content can be used in any theme (a different version of the helper plugin here is used solely to generate navigation links based on the page hierarchy structure).

Going Multisite

We are in the process of changing this site to run as WordPress multisite, meaning each of the certifications will be it’s own WordPress instance. This also means we can easily duplicate them as versions we can possibly host for other organizations, and give access to reps to be able to re-brand and customize content.

But There is More

This part is only content; the other pieces will include recommendations for what we want all participants to develop- their own personal “toolkit” to organize resources, ideas, they come across in going through the certification– ones that are relevant to their own scope of work.

There will also be a CC Certification community, a social connection space for asking/answering question, giving feedback.

And there is a Quest Bank— a place where we send people for tasks to do that demonstrate their application of what they are learning in the proces.

It’s all connecting together.

“Lego mindstorms nxt cable” by ChristianReitter is licensed CC BY-SA