Figure out a way to keep old versions of docs for historical reference

[WasabiFan]

It would be great if we could keep versions of docs for old kernels available so that people can reference information for previous releases. I'm imagining some form of a page_version property that generates a dropdown or other control on all versions of the page. We'd need to make a copy of a page and change its name to archive it.

[dlech]

Old versions are not supported, so there is no reason to keep old information around. If someday we have a stable version and a development version, then perhaps implementing something like this would be worthwhile.

[WasabiFan]

Yep, this would mainly be for whenever "ev3dev stable" happens. I'm just trying to document it so that there is a centralized set of desired features.

[WasabiFan]

I'm now taking a closer look at this to see how we can make this a reality, with planned ev3dev-stretch work on the horizon and multiple kernel versions to maintain as a result.

We have an existing tab-based mechanism for different versions of the same content. We use the tabs mainly for client OSes currently, where sections of instructions (or whole pages) are dependent on the OS that the user chooses. We now want to add the ability to switch between documentation versions, so that you can view documentation for ev3dev-stretch or ev3dev-jessie interchangeably. This is undoubtedly going to stretch (get it? stretch?) the limits of vanilla Jekyll, but I suspect we can still do it in a user-friendly manner if we design it properly.

I don't have a concrete design yet, however I do have some thoughts and goals:

• A system similar to what I described in os tabs should be separate pages #309 seems like a good starting point.
  • Tabs are not an option.
  • A banner below the nav bar would be nice.
• We should aim to integrate this with our OS-specific selection mechanism.
• We need to decide on a scope. Do we want to be able to version tutorials? Landing pages?
• We do not want to load multiple versions of a page into memory unless required.
• This system should handle whole-page versioning as well as small section versioning. These two functions should look the same to the user, even if they're different internally.
• We need to decide the extent to which we support JavaScript-less browsers.
• We should look into using Angular or another similar framework to lessen the use of JQuery-based HTML construction.

I'm working on a solution that addresses these points while seriously considering the technical side of the final result.

[ddemidov]

May be something similar to what readthedocs.org does? They have a small floating button in the bottom right corner which you can use to select version of the documentation. See example here: http://python-ev3dev.readthedocs.io/en/latest/

[WasabiFan]

Good thinking; I hadn't considered that example. The technical side of such a design would be tough with Jekyll, but it really won't get easier with any other design 😆

I'm imagining that something similar to the readthedocs.org control with segments for each option (OS, version, etc.) might work well UX-wise.

[rhempel]

I agree with Denis - maybe start a branch for documenting the new version and generate each branch as its own sub site - that makes it easier to merge commits across the branches too.

[WasabiFan]

This is where it gets tricky 😉 This repo includes all the configuration, styles and general content (e.g. news and homepage) that really should be universal and are expected to have a single "master" copy. My worry with branching is that we'd end up with style and documentation modifications mixed in together, and then sorting out the mess would be near-impossible.

On the other hand, having two or more copies of the same file (one for each combination of ev3dev version and client OS) in the same repo also seems rather ugly, so I am not ready to go full-on down that route. Submodules seem like they may offer a nice solution, but I'm not sure exactly how or even whether they would work on GitHub Pages.

[dlech]

We need to decide on a scope. Do we want to be able to version tutorials? Landing pages?

I suggest everything under docs/ and nothing else.

I like the idea of basically namespacing the url, like /docs/ev3dev-jesse/ev3/windows/getting-started.

I think between Jekyll's dynamic include (variable as file name) and relative include features we can make it happen with minimal duplication.

Multiple repositories is actually a possibility as well. The way GitHub pages is setup, there are two types of repositories. One for organizations and one for projects. Project pages actually show up as a subdirectory of the organization page. For example if you visit http://www.ev3dev.org/grx, you will find the docs served up by https://github.com/ev3dev/grx/tree/gh-pages. It is not quite ideal as it would require one GitHub repository per folder and you only get one folder level (e.g. you couldn't have multiple repositories hosted under /docs).

[WasabiFan]

I like the idea of basically namespacing the url, like /docs/ev3dev-jesse/ev3/windows/getting-started .

The issue I have with that is that "namespacing" the URL leaves you with no canonical version of the page. If we want to point someone to the guide without knowing their OS, we'd need to manually create a page with links to the various versions. And we'd need to do that for every page and every combination of variables 😢 I think that the biggest limiting factor here is that we can't dynamically create pages. Maybe we need some sort of a preprocessor... but I really don't want to start strapping additional stuff to our build just to achieve a suboptimal experience.

I think between Jekyll's dynamic include (variable as file name) and relative include features we can make it happen with minimal duplication.

I don't think the relative one will help us, because it requires that the template is within the file's parent directory. We can probably rig something together with the normal includes, but our template directory is going to get really full! 😁

Multiple repositories is actually a possibility as well. The way GitHub pages is setup, there are two types of repositories. One for organizations and one for projects. Project pages actually show up as a subdirectory of the organization page. For example if you visit http://www.ev3dev.org/grx, you will find the docs served up by https://github.com/ev3dev/grx/tree/gh-pages. It is not quite ideal as it would require one GitHub repository per folder and you only get one folder level (e.g. you couldn't have multiple repositories hosted under /docs ).

We have an issue here with search capability. For our search mechanism to work, every page must be known at build time. We should be able to get the same effect with submodules, though.