Revamped Docs Site

Hey All,

For those of you that haven’t been to https://docs.chef.io 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 https://docs.chef.io/feedback.html.

Thanks!

— cwebber

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:cwebber@chef.io]
Sent: Friday, September 25, 2015 07:21
To: chef@lists.opscode.com
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

We appreciate the effort!

On Fri, Sep 25, 2015 at 6:23 AM, Alex Neihaus architect@air11.com 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:cwebber@chef.io]
Sent: Friday, September 25, 2015 07:21
To: chef@lists.opscode.com
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

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 <
chahn@cognitivemedicine.com> wrote:

We appreciate the effort!

On Fri, Sep 25, 2015 at 6:23 AM, Alex Neihaus architect@air11.com 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:cwebber@chef.io]
Sent: Friday, September 25, 2015 07:21
To: chef@lists.opscode.com
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

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 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 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 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 sirosen@globus.org 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 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 <chahn@cognitivemedicine.com mailto:chahn@cognitivemedicine.com> wrote:
We appreciate the effort!

On Fri, Sep 25, 2015 at 6:23 AM, Alex Neihaus <architect@air11.com mailto:architect@air11.com> 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 http://chef.io/ page to refer to GitHub which refers back to chef.io http://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:cwebber@chef.io mailto:cwebber@chef.io]
Sent: Friday, September 25, 2015 07:21
To: chef@lists.opscode.com mailto:chef@lists.opscode.com
Subject: [chef] Revamped Docs Site

Hey All,

For those of you that haven’t been to https://docs.chef.io 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 https://docs.chef.io/feedback.html.

Thanks!

— cwebber

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 cwebber@chef.io 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 sirosen@globus.org 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 <
chahn@cognitivemedicine.com> wrote:

We appreciate the effort!

On Fri, Sep 25, 2015 at 6:23 AM, Alex Neihaus architect@air11.com
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:cwebber@chef.io]
Sent: Friday, September 25, 2015 07:21
To: chef@lists.opscode.com
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