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

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.