Hi all Some time ago we created a new project called Puppet Docs. This took our existing reference documentation (which is auto-generated from the Puppet Core source code) and added together some pages from the Wiki and some new content. That content was published at http://docs.puppetlabs.com. We''re now discussing whether it is a good idea to separate our documentation from the Puppet Core. What we''re proposing is to move all the content from Puppet Docs (barring MCollective - which will stay in the Mcollective repository) into the Puppet Core repository, probably under a directory called "docs". The documentation will still be published onto the Puppet Docs site when updates occur but the "code" itself will be maintained in the same repository as the Puppet core code. The advantages to this we see as: 1. It''s simpler to have the code and the docs in the same place 2. It lowers the barrier to entry for contributors - only having to maintain one repository and work from one repository. 3. We hope it''ll encourage people to update Docs more when they make changes if they have to only commit code to one repository. 4. One project/place to log documentation tickets rather than two separate Redmine projects. We''re seeking feedback on this idea from the community before we proceed. Regards James Turnbull -- Puppet Labs - http://www.puppetlabs.com C: 503-734-8571 -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Hi James, Sounds very pragmatic and adds some aforementioned structure continuity for the project. Just wondering if there were any disadvantages thought of during the brainstorming to implement this change? I can''t think of any off-hand but I''d guess you and others at Puppet Labs spent more than the last 3 minutes contemplating this change. ;) Thanks, -Mark On Dec 20, 2010, at 12:38 PM, James Turnbull wrote:> Hi all > > Some time ago we created a new project called Puppet Docs. This took > our existing reference documentation (which is auto-generated from the > Puppet Core source code) and added together some pages from the Wiki and > some new content. That content was published at http://docs.puppetlabs.com. > > We''re now discussing whether it is a good idea to separate our > documentation from the Puppet Core. What we''re proposing is to move all > the content from Puppet Docs (barring MCollective - which will stay in > the Mcollective repository) into the Puppet Core repository, probably > under a directory called "docs". > > The documentation will still be published onto the Puppet Docs site when > updates occur but the "code" itself will be maintained in the same > repository as the Puppet core code. > > The advantages to this we see as: > > 1. It''s simpler to have the code and the docs in the same place > 2. It lowers the barrier to entry for contributors - only having to > maintain one repository and work from one repository. > 3. We hope it''ll encourage people to update Docs more when they make > changes if they have to only commit code to one repository. > 4. One project/place to log documentation tickets rather than two > separate Redmine projects. > > We''re seeking feedback on this idea from the community before we proceed. > > Regards > > James Turnbull > > > -- > Puppet Labs - http://www.puppetlabs.com > C: 503-734-8571 > > -- > You received this message because you are subscribed to the Google Groups "Puppet Users" group. > To post to this group, send email to puppet-users@googlegroups.com. > To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. > For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en. >-- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
Mark Stanislav wrote:> Hi James, > > Sounds very pragmatic and adds some aforementioned structure > continuity for the project. Just wondering if there were any > disadvantages thought of during the brainstorming to implement this > change? I can''t think of any off-hand but I''d guess you and others at > Puppet Labs spent more than the last 3 minutes contemplating this > change. ;) >I don''t see any major disadvantages to the community. It may mean documentation updates slow up a little as we ensure all changes have a ticket (some are a little ad hoc right now - for example I might fix a typo or spelling error in a commit and push that without a review). To move it to core we''ll have tickets for each commit and push each for review to the -dev list probably. But yes I am well known for not having a life and think about these things a lot. :) Regards James Turnbull -- Puppet Labs - http://www.puppetlabs.com C: 503-734-8571 -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On Dec 20, 11:38 am, James Turnbull <ja...@puppetlabs.com> wrote:> We''re now discussing whether it is a good idea to separate our > documentation from the Puppet Core. What we''re proposing is to move all > the content from Puppet Docs (barring MCollective - which will stay in > the Mcollective repository) into the Puppet Core repository, probably > under a directory called "docs".[...]> We''re seeking feedback on this idea from the community before we proceed.I am all in favor of maintaining the documentation together with the code. That''s the way it ought to be, as far as I''m concerned. John -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On 12/20/2010 06:38 PM, James Turnbull wrote:> Hi all > > Some time ago we created a new project called Puppet Docs. This took > our existing reference documentation (which is auto-generated from the > Puppet Core source code) and added together some pages from the Wiki and > some new content. That content was published at http://docs.puppetlabs.com. > > We''re now discussing whether it is a good idea to separate our > documentation from the Puppet Core. What we''re proposing is to move all > the content from Puppet Docs (barring MCollective - which will stay in > the Mcollective repository) into the Puppet Core repository, probably > under a directory called "docs".I''m in favor of this. - Felix -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On Tue, 2010-12-21 at 09:43 +0100, Felix Frank wrote:> On 12/20/2010 06:38 PM, James Turnbull wrote: > > We''re now discussing whether it is a good idea to separate our > > documentation from the Puppet Core. What we''re proposing is to move all > > the content from Puppet Docs (barring MCollective - which will stay in > > the Mcollective repository) into the Puppet Core repository, probably > > under a directory called "docs". > > I''m in favor of this.+1 M. -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
One of the questions I have is who do you expect to work on documentation? If you really expect developers to do it primarily, then having it in the code repository is fine. If you want tech-writers, or users who might be a little more scared of working with the code in puppet proper, having it separate may encourage more contributions. It can be a bit daunting to a person just getting started in open source to have to create a branch, send a patch, rebase etc to get a typo fixed. It''s not all-together easier in a separate repository, but the speed at which things change is different so rebases, and such may be easier or less scary. That being said, for me it doesn''t make much of difference. Having one more repository to work in out of the dozens I spend time doesn''t really add incremental cost. stahnma -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
On 12/21/2010 03:55 PM, Michael Stahnke wrote:> One of the questions I have is who do you expect to work on > documentation? If you really expect developers to do it primarily, > then having it in the code repository is fine. If you want > tech-writers, or users who might be a little more scared of working > with the code in puppet proper, having it separate may encourage more > contributions. It can be a bit daunting to a person just getting > started in open source to have to create a branch, send a patch, > rebase etc to get a typo fixed. It''s not all-together easier in a > separate repository, but the speed at which things change is different > so rebases, and such may be easier or less scary. > > That being said, for me it doesn''t make much of difference. Having > one more repository to work in out of the dozens I spend time doesn''t > really add incremental cost.The use of the main repository still allows for documentation bugs to be filed, no? No need for the user to clone any repo, or is the intent indeed to make the users submit per patch only? Regards, Felix -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
2010-12-20 18:38, James Turnbull wrote:> We''re now discussing whether it is a good idea to separate our > documentation from the Puppet Core. What we''re proposing is to move all > the content from Puppet Docs (barring MCollective - which will stay in > the Mcollective repository) into the Puppet Core repository, probably > under a directory called "docs".[...]> The advantages to this we see as: > > 1. It''s simpler to have the code and the docs in the same place > 2. It lowers the barrier to entry for contributors - only having to > maintain one repository and work from one repository. > 3. We hope it''ll encourage people to update Docs more when they make > changes if they have to only commit code to one repository. > 4. One project/place to log documentation tickets rather than two > separate Redmine projects.Maybe we will then get the Puppet documentation installed along with Puppet, like most programs do? That would be nice. Another advantage is that the installed documentation will then be for 2.6.17 when I install 2.6.17, for 4.7.11 when I install that, and so on. I''m for it! /Bellman -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
2011/1/5 Thomas Bellman <bellman@nsc.liu.se>> 2010-12-20 18:38, James Turnbull wrote: > > > We''re now discussing whether it is a good idea to separate our > > documentation from the Puppet Core. What we''re proposing is to move all > > the content from Puppet Docs (barring MCollective - which will stay in > > the Mcollective repository) into the Puppet Core repository, probably > > under a directory called "docs". > [...] > > The advantages to this we see as: > > > > 1. It''s simpler to have the code and the docs in the same place > > 2. It lowers the barrier to entry for contributors - only having to > > maintain one repository and work from one repository. > > 3. We hope it''ll encourage people to update Docs more when they make > > changes if they have to only commit code to one repository. > > 4. One project/place to log documentation tickets rather than two > > separate Redmine projects. > > Maybe we will then get the Puppet documentation installed along with > Puppet, like most programs do? That would be nice. > > Another advantage is that the installed documentation will then be > for 2.6.17 when I install 2.6.17, for 4.7.11 when I install that, > and so on. > > I''m for it! > > > /Bellman > > --Alright...thanks > You received this message because you are subscribed to the Google Groups > "Puppet Users" group. > To post to this group, send email to puppet-users@googlegroups.com. > To unsubscribe from this group, send email to > puppet-users+unsubscribe@googlegroups.com<puppet-users%2Bunsubscribe@googlegroups.com> > . > For more options, visit this group at > http://groups.google.com/group/puppet-users?hl=en. > >-- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscribe@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.