Allow site on master to be always publishable

[parkr]

At the moment, we can only publish our website with each release. If updates or fixes are merged to master after docs for a new feature are brought in, our hands are tied. We can't publish the site patches until we release a new version. I'd like to change this.

My thought is to add a new item to site/_config.yml called, perhaps, latest_release that we can use for {% if %} blocks that only render the enclosed docs if the feature is part of the latest release or below.

Alternatively, we can come up with a cool design for a note that says "As of v1.3.1", or something.

This would allow us to publish without any worry that we'd push out docs for unreleased features.

Thoughts?

/cc @benbalter @robmuh @mattr-

[troyswanson]

I think the config value makes a lot of sense, but doesn't cover all of the bases (as of right now, at least). With #1953, I set up the docs index to be defined by a data file. Any time a new feature is added, a new document file should be created about it, which would require that data file to be updated. I suppose a value in the YAML front-matter for the new feature document could be created.

I'm more of a fan of the second option, but it might cause some problems. If the site shows features that exist "as of v2.0.0", but that version isn't even released yet, I imagine that would cause some confusion. It might make sense to modify some of the designs to give more hints about which version is the latest released version and which is currently in development.

[doktorbro]

You have two options:

1. Angular style

   Place the version information inside of URL. It ends up in a lot of copies of the same feature and lot of 404s:

   • http://jekyllrb.com/docs/current/feature/ — current stable branch (do you have only one?)
   • http://jekyllrb.com/docs/master/feature/ — master branch
   • http://jekyllrb.com/docs/v1.2.3/feature/ — 1.2.3 version
   • not found (404) for http://jekyllrb.com/docs/current/feature/ — one day feature is gone

2. Jquery style

   Place the version information inside of website. You maintain only one document. The URL lives forever:

   • http://jekyllrb.com/docs/feature/ — for all versions and branches

[benbalter]

I like the idea of giving something a URL and not messing with it. What if, post 2.0.0 we...

• Create collections for each major thing we document e.g., filters, tags, and configurations
• Each document within the collections would have YAML front matter with a minimum and maximum version, and other meta data
• Add a version string to _config.yml
• Add a tag that is smart enough to compare semantic versions using pessimistic operator syntax

That way, we'd still have pages like we have now "getting started", "plugins", etc., but individual features would have their own unique, permanent URL. When visiting an individual feature, it could be published immediately upon hitting master, but the template would put a big warning on the page, e.g., "This page documents a not-yet-released feature", or "This feature has been deprecated in version 1.0.0". and if within a Page we need to version something we'd use the tag, e.g., {% requires_version "1.2.0" %}.

I'm thinking that we should be dog fooding this on two fronts:

1. It's a great opportunity to drive development of collections with a real use case
2. It's a great opportunity to create a design pattern for other projects to use Jekyll for technical documentation

[doktorbro]

It's a great opportunity to create a design pattern for other projects to use Jekyll for technical documentation

👯 👯 👯

[mattr-]

👍 to what @benbalter said

[rwxrob]

Just noticing this issue now and I have to say +1 to everything --- especially one URL and the importance of coming up with a documentation practice that can be used for other things (since I look forward to doing that myself).

I'd add that most Oreilly and other reputable books about technology that has undergone major revision changes (JavaScript, HTML, Python) include everything inline with call outs to features that are new or removed. If there is something particularly different there is a box discussing that difference.

I think for search engines alone it is very important to keep one URL. This also really helps later with things like the Wayback Machine Internet Archive.

[ivantsepp]

I'm actually a fan of multiple urls. Not everyone is on the latest release and developers need to know how things use to work before. Rails is a great example of this.

Instead of introducing complexity through variables to "version" the Jekyll documentation, why not use git? Whenever there are fixes or changes to documentation, we should merge it with master AND with v1-stable branch. Then, you can publish to gh-branch by checking out v1-stable branch and doing bundle exec rake site:publish.

Does that make sense? What do you guys think about that idea?

[parkr]

Well, I guess I can use an include rather than a custom liquid tag.