Puppet

I believe this is a terrible idea. But I’m willing to be convinced otherwise, because I may not have a full understanding of the pros and cons here. (Also, didn’t we switch to and then away from this model at least once already, before I joined the company?)

Here’s my current assessment of this suggestion:

Pros that are not actually pros:¶

• Can associate the docs with a specific version of Puppet by just checking out the appropriate tag.
  • Except we don’t currently have versionable comprehensive feature documentation, so the content you’d be tying to that tag would be a melange of <0.25, 2.6, and 2.7 content.
  • The tag would show you what the docs LOOKED like at a certain point in Puppet’s history, but wouldn’t necessarily be up-to-date for that tag. We frequently find new quirks or issues with a certain version, such that if you wanted the straight dope on 2.7.4, you would do well to check the 2.7.9 tag. The fact that we can’t guarantee complete knowledge about a release simultaneous with that release obviates any benefit from joining docs and code histories at the commit level. Good documentation requires the ability to update the docs for a specific version without doing an explosive upstream rebase.
• It’ll be easy to update the docs when making changes to Puppet, because they’ll be right there. This means less barrier to contributions.
  • Docs aren’t tests, and can’t be added at commit time by developers the way tests can. With tests, there’s an easy file-hierarchy mapping showing where each test should go and what its content should be; documentation doesn’t follow the source code like that, which means it needs a lot more narrative planning. In practice, docs commits will be going through our tech writers anyway, so making the source files more accessible to engineering doesn’t win us much.
  • This would make the docs source LESS accessible to the tech writers doing the bulk of the edits. I assume PE docs would go in the enterprise-dist repo and dashboard/console docs would go in their associated repo as well? Likewise with the open-source add-ons like cloud provisioner? So instead of our writers working with one or two repos most of the time, they’d be working with like four or five. Meanwhile, docs are right at the engineers' fingertips, but they’re not the ones writing final copy for the website anyway.
• Users have easy access to the docs right from the source code.
  • Users instinctively find the information they need by typing things into Google, not by digging through wherever their packaging system installed Puppet and reading a bunch of not-up-to-date Markdown files.

Cons:¶

• Would add large amounts of thrash to the Git history of both Puppet and the docs, limiting insight into the history of either.
• Would muddy and interfere with access control processes for the core repo, since docs would need a different commit path that didn’t go through the senior engineers.
• Would limit our ability to re-organize the docs or move to a different content generation/management system in the future.

So… unless there’s something really important that I’m missing, I’m inclined to reject this.