Issue #5683 has been updated by Nick Fagerlund.
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.
----------------------------------------
Refactor #5683: Move Puppet Docs into Puppet Core
https://projects.puppetlabs.com/issues/5683#change-55082
Author: James Turnbull
Status: Needs Decision
Priority: Normal
Assignee: Nick Fagerlund
Category: documentation
Target version: 2.7.x
Affected Puppet version: 2.6.4
Keywords:
Branch:
Move the Puppet Docs into Puppet Core.
Steps:
1. Create docs directory
2. Move source/guides and source/reference into directory
3. Create appropriate rake tasks (use Puppet Docs ones) for ref page creation
4. Embed Docs into Puppet Docs repo as a sub-module in same way mcollective is
5. Re-write website creation tasks to reflect changes
6. Merge Puppet Documentation Project (and update references to in Docs and
elsewhere) into Puppet Core project
7. Appropriate notifications - what to do about existing forks?
8, Others?
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
