documentation should be versioned (ie, 1.0 docs should be easy to find)

I’m on 1.0 and it’s unlikely I will upgrade to 2.0 very soon.

  1. It’s pretty jarring (and frustrating) to suddenly have all new docs with the 2.0 release. It makes sense that 2.0 is the default, but I still need to reference 1.0 docs occasionally. As will the majority of your users for a while since most of us aren’t gonna switch over right away, if we ever do. So where do we find them? It’s not at all clear (seriously, where can I find them?). Lodash and react-router are 2 examples of projects that do versioned documentation well if you need examples. Lodash for instance, has a dropdown on their docs page allowing you toggle what version you’re looking at, and react-router has docs for all their major versions linked directly in the readme. I can dig through the chartjs 1.0 code to figure out what I need to, but obviously I’d prefer not having to do that.
  2. Should I choose to upgrade from 1.0, there should be a clear and easy to follow upgrade guide linked somewhere in the readme or the documentation, or both. Yes, I can read the release notes and the docs, but if I’ve already been using 1.0 and just want to upgrade, a clear and concise description of the api differences and what I might run into would make things 10x easier

Author: Fantashit

1 thought on “documentation should be versioned (ie, 1.0 docs should be easy to find)

Comments are closed.