Consistent way to indicate versions, when relevant

[tachyondecay]

LIkely most of the documentation will be either version-agnostic or apply to the most recent version. However, the particular situation I’m thinking of would be screencasts that demonstrate a concept using a version of Symphony from years ago.

In many cases these screencasts are still useful; Symphony’s backend hasn’t changed too much over the years, and most of the major concepts are the same. We should still use those videos, when possible, at least until someone gets around to making updated versions. But it could confuse new users watching those videos to see an interface slightly different from theirs.

So we should establish a consistent way to indicate when a page applies to or features details from a specific version of Symphony. I’m not too familiar with Jekyll, but I’m assuming there’s some way to include templates or otherwise abstract this? Something along the lines of:

This screencast features a previous version of Symphony ([version number]). The concepts it demonstrates still apply to the current version, and we have noted any changes below that affect the tutorial.

This could appear as a little note at the top of the page, and then as implied below, anything that has changed since the screencast was made can be listed below the video, e.g., "Utilities editor has since been removed; use your preferred text editor instead."

[bernardodiasc]

This is a nice feature to have. Currently, some files I copied already have meta informations, like this:

https://github.com/symphonycms/docs.getsymphony.com/blob/gh-pages/docs/articles/combining-symphony-with-nginx.md#meta

We can use this in the Front Matter (the YML between double --- in the top of all files). This creates variables to be used in the template, and as in XSL, Jekyll provides ways to do this.

If you are able to make an example of the output expected I can make this work easily.

Related to the #8 (3. Article front matter).

Thanks!

[johnpuddephatt]

Hmmm. I'm not sure what the best solution is here.

If we include version information in the front matter, this would need updating on each file for every release. While this is perhaps the right thing to do, I'm concerned that in practice it would make the documentation laborious to maintain.

[bernardodiasc]

Indeed. I think all docs need to be applicable, otherwise need to be updated, and if not possible, removed. In this site can't have any useless page.

Said that, two useful information about this is the current Sym version when the page was written/updated and the date (created and modified).

[tachyondecay]

I don’t think we need to include version information on all pages. I'm talking specifically about situations where the doc in question is useful but has outdated information that we can’t update—i.e., because it’s a screencast. Rather than every contributor having their own way of letting people know about this, I would love a standard note.

Looking at the Jekyll templating docs, I guess what I’m thinking of is an include template, along the lines of:

<div class="note version-aware">
    <p>This features a previous version of Symphony ({{ include.version }}). The concepts it demonstrates still apply to the current version, and we have noted any changes below that affect the tutorial.</p>
</div>

(I don't know if Factory has any specific classes designed for notification/warning callouts. I'm envisioning the above creating a little notice at the the top of the article, just below the headline.)

And then in the article itself, we'd do {% include version_note.html version='2.4' %} to indicate that the article/screencast/whatever refers to Symphony 2.4.

This will let us include those docs that are still useful while notifying users that the material in them might sometimes look different from what they are seeing in their current Symphony installation. Then, when we have the time after we’ve finished adding existing docs and plugging holes, we can go back and update, re-record, etc., and remove the template.

[johnpuddephatt]

ok, thanks for the clarification @tachyondecay – I think what you're saying makes a lot of sense, especially in the case of screencasts etc which are a lot harder to update than text-based information.

[bernardodiasc]

Ready here https://github.com/symphonycms/docs.getsymphony.com/blob/gh-pages/_layouts/docs.html#L28-L30

Still don't have any style, just a regular paragraph.

To use just include the variable version (this variable name can be changed) in the front matter, for instance, the markdown files that need this advice, just include in the top of the file:

---
version: 2.4
---

[tachyondecay]

That looks good! We can worry about the styling later. Thanks for taking care of it.