Ohai Chefs!
We’re starting to make some exciting changes to our documentation at https://docs.chef.io and will be sharing them with you as they roll out over the next few months. The changes will improve the quality and usability of our documentation and make it easier for us to give you more accurate content, more code examples, and an easier contribution model.
The first of these changes, which we’re rolling out today, simplify how we handle feature versions:
-
Version-aware content. Starting today, we will include an annotation such as “New in Chef client 12.14” on new items in the documentation. We will use similar annotations for items that have been deprecated or removed. These annotations indicate when a change was introduced. As a result, you’ll be able to use the latest version of the docs no matter what dot release you’re on. We have started adding version annotations for new dot releases of projects, starting with Chef client 12.14, and we will be adding version info for older dot releases over time.
-
Aggregated release notes. Studies of site traffic tell us that the release notes are the most viewed topic for any version-specific doc set available from the “filter view” drop down menu (e.g. Chef 12.13). Prior to today, the only way to look at the release notes for a specific version was to change the filter in the left nav. We have now consolidated all release notes into https://docs.chef.io/release_notes.html and https://docs.chef.io/release_notes_server.html. These new topics contain all of the release notes for the current major version of the Chef client and server, respectively. The release notes are aggregated and organized in much the same way as a change log, and they are easy to search. We will add consolidated release notes for other projects (such as Chef DK) shortly.
-
Going forward, no new doc sets under docs.chef.io/release/. By making our main content version aware and providing consolidated release notes, we no longer need to add special (largely duplicated) versions of docs sets to the filter view drop down menu for new dot releases. We’re taking our first stab at this new way of doing things with the Chef client 12.14 release.
There’s more to come, but we hope you like our first steps!