[chef] Re: Re: Re: Re: RE: Revamped Docs Site

[Stephen Rosen < >]

I'm not clear if I was just a dummy all this time, or if I just missed this addition as part of this redesign?

If it's new, *thumbs up*!

If it's old, sorry for being ignorant.

Anyway, I think my complaint can be reduced down into:

I didn't see the version number in any obvious/intuitive place.
I don't think "Chef: current" is very clear.

I'd rather see it listed with the current version, as is the convention for Ruby (includes version in URI) and Python (URI and that version dropdown menu) docs.

That also nicely means that if I go to http://ruby-doc.org/core/Class.html , I get bounced to http://ruby-doc.org/core-2.2.3/Class.html , and I know that I can find the 2.2.1 version of that doc at http://ruby-doc.org/core-2.2.1/Class.html

I think that's a desirable structure, though not necessarily the only one.

That also plays into an issue in which after arriving at https://docs.chef.io/knife_bootstrap.html , it isn't at all clear how to get to https://docs.chef.io/release/11-18/knife_bootstrap.html

Toggling the version of "Chef Client" in the dropdown does not have the desired effect, since it takes you back to the Chef Client landing page.

I think that's fine when you're going to a version where a feature or command doesn't exist or has changed names, but `knife bootstrap` is still `knife bootstrap`.

Regardless, version numbers, whoo! Thanks!

-Stephen

On Fri, Sep 25, 2015 at 2:46 PM Christopher Webber < "> > wrote:

So we are still working out the kinks, but… you can at least go look at this for specific versions of chef…

https://docs.chef.io/release/server_12-2/ctl_chef_server.html#org-user-remove < 12.2

https://docs.chef.io/release/server_12-1/ctl_chef_server.html#org-user-remove < 12.1 (I will note that that anchor doesn’t work, because that command isn’t there)

I know it isn’t super clear when it was added, but at least you can choose the version of the docs that make sense for what you are running.

http://i.cwebber.net/Monosnap_2015-09-25_12-43-45.jpg

Thanks for the feedback!

— cwebber

On Sep 25, 2015, at 12:37 PM, Stephen Rosen < " target="_blank"> > wrote:

First of all, I like the redesign a lot.
The new navbar on the left seems particularly nice.

However, this is an opportunity to voice a gripe I've had for a long time about the docs, and which I think is both fixable in the short term and much more important than a mobile-friendly redesign.

Can we please, please, pretty please, get version numbers noted on pages?
This is especially important for `knife` docs.

It's frustrating to look at a page on the doc site and say "Hmm. Was this page updated after Chef 12 was released?"

I'm not insisting that every version of every command be documented on the site -- although, frankly, I think that is a highly automatable process -- but just that when I look at the info for `chef-server-ctl org-user-remove` ( https://docs.chef.io/ctl_chef_server.html#org-user-remove ) I can know which version of Chef that documentation refers to.

I pick that example because the `knife edit` command given there is, to the best of my knowledge, wrong for Chef 12.

If I can't have the right command for the current version, at least tell me that the doc dates from an earlier version of Chef.

All that said, I stand by my initial statement that the redesign is good and gives me the warm fuzzies.

Thanks very much,

-Stephen

On Fri, Sep 25, 2015 at 9:05 AM Christopher Hahn < " target="_blank"> > wrote:

We appreciate the effort!

On Fri, Sep 25, 2015 at 6:23 AM, Alex Neihaus < " target="_blank"> > wrote:

Hi. This is a very nice update and much appreciated.

I’m a newbie – and I find it frustrating for doc on the relevant chef.io page to refer to GitHub which refers back to chef.io. I also wish all options were document, with relevant examples on a page somehere and not just in the help text of the command itself. IMO, the complete product doc should be on your site. Knife ec2 (which I am currently learning) is one such example.

Alex

From: Christopher Webber [mailto: " target="_blank"> ]
Sent: Friday, September 25, 2015 07:21
To: " target="_blank">
Subject: [chef] Revamped Docs Site

Hey All,

For those of you that haven’t been to https://docs.chef.io since about 21:00 UTC yesterday (2015-09-24), we have launch a major redesign of the Docs site. The content hasn’t changed significantly but, along with a fresh new design, it is now browsable on mobile and tablet. Hopefully y’all feel like it is as much of an upgrade as we do. Please let me know if you hit any issue. Additionally you can provide feedback by going to https://docs.chef.io/feedback.html.

Thanks!

— cwebber