6 ms·

Am I totally missing some obvious Chef documentation? The entirety of the documentation when I last looked seemed to be the wiki + the one 50-page O'Reilly boo

Am I totally missing some obvious Chef documentation? The entirety of the documentation when I last looked seemed to be the wiki + the one 50-page O'Reilly book. I ended up literally printing out the wiki. (And the wiki seemed to be in a state of pretty extreme flux and/or disagreement with what blog posts suggested was best practice.) The business model of the companies promoting Puppet and Chef seems to be to charge for support and/or hosted services. Which is fine. But is it leading to abysmal documentation?

techscruggs 15y ago
I was a bit confused by the "excellent reference documentation" regarding Chef, as well. The documentation I have read has been out of sync, occasionally contradictory piece-meal. I have yet to find anything more useful than just reading recipes. I wonder if the author knows of resources other than that book and the wiki.
- bryanwb 15y ago
  I have had a very different experience from yours. I have found the Chef wiki to be consistently well written and consistent. Please note that I have only been working with Chef for the past three weeks, so they may have been brought into that state quite recently.
  - techscruggs 15y ago
    That would be a great surprise! I haven't been on the wiki form ~5 months, which does make my opinion a bit dated.
- Woost 15y ago
  The chef irc channel can be helpful (http://wiki.opscode.com/display/chef/IRC http://wiki.opscode.com/display/chef/IRC)
  - pwelch 15y ago
    I agree. What Chef lacks in documentation it makes up for it in community support. I have only been messing with Chef for a few weeks off and on but there is always someone to answer my questions in the IRC channel. Often it is someone from Opscode.
sheff 15y ago
I tried out both Puppet and Chef a while ago, and was also a bit confused by the Chef documentation when trying to do anything beyond the basics. While not brilliant, the Puppet docs seemed better and when added to the Pro Puppet book ( http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/1430230576 http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/143023057... ) are more than adequate, so I just picked Puppet on that basis alone, and have not had any issues. Another useful tool , in conjunction with Puppet/Chef is Blueprint which lets you build configurations from existing servers , http://devstructure.com/ http://devstructure.com/ .
- techscruggs 15y ago
  Have you used Blueprint? I am really interested in it. Honestly, it seems like a bit of magic to me and wonder how well it works and what its limitations are.
nigelk 15y ago
"The business model of the companies promoting Puppet and Chef seems to be to charge for support and/or hosted services. Which is fine. But is it leading to abysmal documentation?" This is one of the reasons we're moving Puppet Labs from being a support company to a product company, and not for hosted services. If your bread and butter comes in from support, you have no incentive to actually make your product easier to use. There are plenty of enterprise-y software companies who make lots of money operating like this, but that's not the sort of company I want to work for. I'm quite proud of the rapid improvement we've made on the Puppet Docs over the last year since we hired NickF, our most excellent tech writer: http://docs.puppetlabs.com/ http://docs.puppetlabs.com/ I particularly like the solution focused docs he's done, as opposed to the dry reference material that presupposes a lot of knowledge. http://docs.puppetlabs.com/learning/ http://docs.puppetlabs.com/learning/ Anyway, just wanted to point out that that's not our business model. (Product Manager at Puppet Labs)
- lobster_johnson 15y ago
  It's gotten better, but it still is very messy. What it needs above everything else is a table contents that stays with you as you read. The documentation you have now only lists a TOC for the section you're in. And the TOC is tucked away in the right-hand corner and stays there when you scroll. So whenever I dive into your docs, I never get a sense of "where" I am in the whole big ball of string, and I get frustrated. The first page is weirdly arranged. For example, it's got a big headline "Learning Puppet", then "Learn to use Puppet! New users: start here." Then there is a link to "Introduction and Index". I interpret this as being the link to the "new users" guide, and that the next two sections ("Part one", "Part two") are not related. But if you click on "Introduction and Index" you come to a new page which lists the exact same TOC, and has no section named "Introducion". It's confusing. The "reference manual" and "guides" sections are similarly confusing because of the lack of a unified table of contents. The reference is particularly bad because I want to look up something alphabetically ("I want to manage users, so I bet it's called 'user'"), but the reference is arranged by topic.
  - nigelk 15y ago
    Those are all good points, and we know the layout needs to improve. I would add though that once you've gone through the basics, you find yourself primarily living in the Type Reference, which is arranged alphabetically. http://docs.puppetlabs.com/references/stable/type.html http://docs.puppetlabs.com/references/stable/type.html Always happy to get bug reports, feature requests and feedback on the docs... http://projects.puppetlabs.com/projects/puppet-docs http://projects.puppetlabs.com/projects/puppet-docs

techscruggs 15y ago

I was a bit confused by the "excellent reference documentation" regarding Chef, as well. The documentation I have read has been out of sync, occasionally contradictory piece-meal. I have yet to find anything more useful than just reading recipes. I wonder if the author knows of resources other than that book and the wiki.

bryanwb 15y ago
I have had a very different experience from yours. I have found the Chef wiki to be consistently well written and consistent. Please note that I have only been working with Chef for the past three weeks, so they may have been brought into that state quite recently.
- techscruggs 15y ago
  That would be a great surprise! I haven't been on the wiki form ~5 months, which does make my opinion a bit dated.
Woost 15y ago
The chef irc channel can be helpful (http://wiki.opscode.com/display/chef/IRC http://wiki.opscode.com/display/chef/IRC)
- pwelch 15y ago
  I agree. What Chef lacks in documentation it makes up for it in community support. I have only been messing with Chef for a few weeks off and on but there is always someone to answer my questions in the IRC channel. Often it is someone from Opscode.

sheff 15y ago

I tried out both Puppet and Chef a while ago, and was also a bit confused by the Chef documentation when trying to do anything beyond the basics. While not brilliant, the Puppet docs seemed better and when added to the Pro Puppet book ( http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/1430230576 http://www.amazon.com/Pro-Puppet-James-Turnbull/dp/143023057... ) are more than adequate, so I just picked Puppet on that basis alone, and have not had any issues. Another useful tool , in conjunction with Puppet/Chef is Blueprint which lets you build configurations from existing servers , http://devstructure.com/ http://devstructure.com/ .

techscruggs 15y ago
Have you used Blueprint? I am really interested in it. Honestly, it seems like a bit of magic to me and wonder how well it works and what its limitations are.

nigelk 15y ago

"The business model of the companies promoting Puppet and Chef seems to be to charge for support and/or hosted services. Which is fine. But is it leading to abysmal documentation?" This is one of the reasons we're moving Puppet Labs from being a support company to a product company, and not for hosted services. If your bread and butter comes in from support, you have no incentive to actually make your product easier to use. There are plenty of enterprise-y software companies who make lots of money operating like this, but that's not the sort of company I want to work for. I'm quite proud of the rapid improvement we've made on the Puppet Docs over the last year since we hired NickF, our most excellent tech writer: http://docs.puppetlabs.com/ http://docs.puppetlabs.com/ I particularly like the solution focused docs he's done, as opposed to the dry reference material that presupposes a lot of knowledge. http://docs.puppetlabs.com/learning/ http://docs.puppetlabs.com/learning/ Anyway, just wanted to point out that that's not our business model. (Product Manager at Puppet Labs)

lobster_johnson 15y ago
It's gotten better, but it still is very messy. What it needs above everything else is a table contents that stays with you as you read. The documentation you have now only lists a TOC for the section you're in. And the TOC is tucked away in the right-hand corner and stays there when you scroll. So whenever I dive into your docs, I never get a sense of "where" I am in the whole big ball of string, and I get frustrated. The first page is weirdly arranged. For example, it's got a big headline "Learning Puppet", then "Learn to use Puppet! New users: start here." Then there is a link to "Introduction and Index". I interpret this as being the link to the "new users" guide, and that the next two sections ("Part one", "Part two") are not related. But if you click on "Introduction and Index" you come to a new page which lists the exact same TOC, and has no section named "Introducion". It's confusing. The "reference manual" and "guides" sections are similarly confusing because of the lack of a unified table of contents. The reference is particularly bad because I want to look up something alphabetically ("I want to manage users, so I bet it's called 'user'"), but the reference is arranged by topic.
- nigelk 15y ago
  Those are all good points, and we know the layout needs to improve. I would add though that once you've gone through the basics, you find yourself primarily living in the Type Reference, which is arranged alphabetically. http://docs.puppetlabs.com/references/stable/type.html http://docs.puppetlabs.com/references/stable/type.html Always happy to get bug reports, feature requests and feedback on the docs... http://projects.puppetlabs.com/projects/puppet-docs http://projects.puppetlabs.com/projects/puppet-docs