Hi folks,
I've been working on adding content to http://docs.reductivelabs.com
(not pushed just yet) ... the goal for docs.reductivelabs.com is to be
a great place to point people learning puppet, that produces a good
gentle introduction but also contains the meat
of the information, all in one place, without going too far in, but
that also shows you where you can go. It's all open for contribution
(Creative Commons) of course and is based on what is being done with
the Ruby on Rails guides -- contributions can be made using the
"feedback" tab, filing a bug in redmine, or just forking the project
on github and sending a pull request. Most important to mention,
90%+ of the content is borrowed from the Wiki and would not be
possible without it. A huge huge huge thanks there, cannot be said
enough. We have awesome resources adding to our docs and they are
tremendous asset to Puppet Land.
So in getting together what you would need to learn Puppet, and making
it a bit more organized (splitting some articles, merging others,
etc), it's obvious that if we also have this content on the Wiki the
two will drift apart, and we would like to minimize the pain of this
happening. We'd also like to keep all the good things we have going
with the Wiki going. So, seeing we have a process for maintaining
things on the new docsite, and we only intend the docsite for content
that will not change /as/ often, what does everyone think at moving
some of the more introductory pages into the doc site? These would
be things like:
* About Puppet
* Adding Facts
* Development Complete Resource Example
* Development Creating Custom Types
* Development Practical Types
* Development Provider Development
* Exported Resources
* External Nodes
* File Serving Configuration (maybe)
* Getting Started
* Module Organisation
* Module Standards
* Plugins In Modules
* Style Guide
* Using Mongrel (linking to other content still on Wiki)
* Using Passenger (linking to other content still on Wiki)
* Using Stored Configuration
* Using Tags (maybe)
etc
Things that would never move to the doc site would be things like:
* Recipes / Patterns
* FAQ (we may include a subset of the FAQ on the docsite for the
most common items)
* Best Practices At X
* Cool Strategies for X
* Making X work on my platform
* What I Did With X
* Workaround for X
* Development Lifecycle
* Testing information
* Who Is Using Puppet
* etc
(basically most of the Wiki)
Doc site would still link to the Wiki and make folks know of all the
content that was there. We'd also try to spotlight some of the key
Wiki topics.
For those we're thinking about moving, I would suggest leaving all the
actual Wiki pages in place (breaking bookmarks would be terrible), and
replacing their content with a link to the docs page for the content
that is also duplicated there. Where the page content was not wholly
reproduced on the doc site, we would do this to that page.
(absolutely no information loss). The doc site also explains how to
contribute on page 1 (it will when I push it), and we also add this
info to the WIki -- including about what goes where.
We would definitely want to keep any rapidly evolving content on the
Wiki, and the Wiki is definitely the place for site specifc best
practices suggestions, modules, and all that other good stuff.
We then keep our Wiki collaboration space rocking, and we also have a
good resource to point new users to. (I also intend to make a
zipfile of our docs site, so it's easy to download and take with you,
on a plane, etc).
Does that seem reasonable? Other suggestions?
--Michael
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-us...@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.
