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?
"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:
The one persistent thread I've seen with "support-based models", notably Red Hat, is that ... the tools leave you requiring support, and yet the support still sucks (in large part because the support engineers have to use the same crappy tools you do).
I'm not going to pretend I've got the Free Software business model sorted out. But I have noticed that project goals and incentives do line up with results. Debian has a social contract, a constitution, and policy, and the tools to support these. From an ease-of-use / ease-of-maintenance perspective, Debian (and its derivatives) blow RPM-based systems out of the water. And to be clear: the distinction is much less the packaging formats (though that's part of it) and far more the use and management of these tools.
I think there's someone who died recently who made the end-user experience key. While his organization struggled at times, it's emerged in recent years as an absolute behemoth which suggests ultimately that the alignment he chose is better than that of a principle rival.
I'm not going to pretend we've got the Free Software business model perfectly sorted either.
We're producing proprietary software as well as developing/curating open source software projects, and there is a balancing act involved there.
Not to sound too bandwagon-jumpy (I've found the recent hyperbolic public outpouring of grief somewhat distasteful) but I care about user experience and documentation, and I've always believed that focusing on the end user will lead you in the right direction.
> From an ease-of-use / ease-of-maintenance perspective, Debian (and its derivatives) blow RPM-based systems out of the water.
What kind of a comparison (Debian vs. RPM-based) is this? Does dpkg(1), as opposed to rpm(8), really make all the difference in "ease-of-use"?
Of course, I understand what you mean, however, don't you think that if Debian really blew RHEL and SLES out of the water, its adoption in the enterprise server space would be a bit higher? You are kidding yourself if you pretend that the commercial distros are only used because they come with support, and also need support, being intentionally crippled.
Obviously, a meaningful comparison of Debian, RHEL and SLES does not fit into a HN comment, but as someone who has used all three, I would always choose Debian last, and not only because of the lack of commercial support.
(By the way, the main point of the support you get for RHEL and SLES is not access to a guy on the phone. The real value is the L3 support, i.e. bugfixing. As a Debian user who runs into a bug that cripples your system, your options are:
a) fix it yourself
b) pray to $DEITY that Debian developers fix it soon
c) try to expedite b) by harassing Debian developers in bugzilla, which is going to be as inefficient as you'd expect.
As a paying customer of Red Hat or SuSE, you are entitled to and will receive a fix for the bug ASAP, and although ASAP often translates to "a couple of weeks", it is still a hell of a lot better than what Debian can offer.)
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.
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.
> I would add though that once you've gone through the basics, you find yourself primarily living in the Type Reference
Yes, that's were I ended up. I'm way beyond that level now, but I sometimes have to look something up in the docs, and always have to hunt down the URL to that particularly page.
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.
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.
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.
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/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/ .
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.
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?