Puppet Documentation

That would be great. Incidentally, we currently generate HTML named anchors in that document that overlap: some index entires go to the wrong place as a consequence. One page per type would totally solve that. :)

Having one page is fair enough. Sometimes we need to switch from one resource to another. Maybe the TOC should always stay on top and get shortened? My Vote: -1

The length is not a problem in itself, imo. But the formatting is … non-optimal. It actually becomes easier to read when I select “No style” as the page style in Firefox.

Here are a couple of concrete suggestions:

• Don’t f*ck with the left margin! When using the page’s style sheet, the text becomes flush to my browser window’s left edge. Sucks for readability.

• Don’t fck with sizes and things for headings. At least for me, the heading for each type is smaller* than the subheadings within each type, and even than the sub-sub-headings (like the name of each parameter).

• Raise the “heading level” for most things; put the heading for each type inside h2 instead of h3, and the sections within each type should likewise be headed with h3, not h4.

• Use definition lists (dl, dd and dt elements) for parameters, instead of a h5 heading with a paragraph after it.

We actually used to have a one-page-per-type version of the type reference. I burned it to the ground, because it’d been created by hand and was many many versions out of sync with reality (and had no concept of versioning at all, come to think of it).

I’m sure we could find a way to do it maintainably; it’s just a question of whether that would actually enhance the usefulness of the reference. That’s what I’d most like more feedback about.

I’m very interested in Thomas’s suggestion of using DL elements instead of h5s, especially since I think that would eliminate a lot of the element ID conflicts! I also think the Markdown dialect Jekyll is using has extended syntax for those, so that’s nice. I’ll look into this.

Pull request for the changes to Puppet core: https://github.com/puppetlabs/puppet/pull/117 …have tweaked the site CSS, and am about to get started on repairing the older refs.