MDN/Projects/Development/Product Versioning
The problem
Lots of the stuff we document is version-specific. For example:
- how to debug apps on Firefox OS is dependent on the version of Firefox OS you're targeting
- which APIs are available to apps on Firefox OS is dependent on the version of Firefox OS you're targeting
- which exact features are supported by the Firefox Developer Tools is dependent on the version of Firefox you're targeting
...and so on. At the moment we deal with this by adding in little notes here and there. I think this makes the pages harder for developers to use, because they're always having to check whether the features they're reading about are supported in the product version they're working with.
I'd like us to deal with this better. I'd like users to be able to indicate the version of the product they're working with, and then to see the information that's relevant to that version only. So they can say: I'm targeting Firefox OS 1.2, show me the docs for that. I'd also like users to be able to switch from one version of the product to another, and then see the docs for that.
This is a pretty common feature of documentation systems, see docs.python.org/ for the first example I looked at.
What it might look like
I think this is a difficult feature to implement and I don't want to try to prejudge an implementation. And I'm aware that I'm glossing over some difficulties here...
But maybe something like: writers could indicate, somehow, that:
- a page is relevant for a particular range of versions of a product
- particular sections of the page are relevant to a particular subset of that range
- a particular version should be the default
We can do this, perhaps, by having a table of product versions and which revisions of articles belong to that product version, then offering appropriate UX or whatever to select a version and show those versions of pages as they get navigated to, or the latest version of any page not in the list for that version of a product.
Example
So for instance, I could say that:
- the JS Debugger page (https://developer.mozilla.org/en-US/docs/Tools/Debugger) covers Firefoxes 24-26
- the "blackboxing" section of that page (https://developer.mozilla.org/en-US/docs/Tools/Debugger#Black_box_a_source) is only applicable to Firefoxes 25 and 26
- the default version of the page should be 26
If I do this, then the page would display the "blackboxing" section by default, and offer some bit of UI to indicate that the page describes the debugger as it is in version 26. It also offers the user the choice to see the documentation for the debugger in Firefoxes 24 and 25. If the user selects 24, the blackboxing section isn't presented any more.
