Hi all,
Now that (I hope) I''ve fixed the problems in 0.22.2 with 0.22.3,
I''m
prioritizing on documentation, since that''s the biggest complaint
from people right now, from what I can tell.
I''m starting with the introduction, since, of course, that''s
where
everyone else starts, and it has not kept pace with how I talk about
Puppet in presentations and such.
In the course of rewriting it, I had to create some wiki pages for
PRM and modules:
http://reductivelabs.com/trac/puppet/wiki/PuppetRecipeManager
http://reductivelabs.com/trac/puppet/wiki/PuppetModules
The Modules documentation is pretty sparse, so please add anything
you think is important.
Also, in general, I just want to make this clear: I am always
looking for help with the documentation, and I will not be offended
in the slightest if someone rewrites some or all of a given page, or
any of that. The whole point of having these docs on the wiki is so
the community can help with them. I''m a bit too close to the code
sometimes to see the user side well enough to document for it, and I
don''t do the best job of prioritizing on documenting vs. coding. I
*know* the existing docs aren''t very good, and I would greatly
appreciate help making them better.
If you have an idea for better docs, please add that idea. If you
think docs are missing but you don''t think you can write it, please
create a MissingDocumentation page and add it there, then hopefully
someone else in the community can fill in the blanks.
I''d love to have a couple of semi-official documentation wranglers,
people who paid attention to how current the docs are with the code,
and who kept track of changes to the wiki to keep track of what
documents people are making the most changes to and hopefully use
that information to decide when a document should be rewritten.
That being said, I''m currently rewriting the Introduction, as I
mentioned, and I hope to have a new version today. After that, I''m
probably going to create a page to link to platform-specific pages,
and maybe try to come up with some kind of simplistic "feature list"
page, so you can get an idea of what Puppet can do without lots of
investigation.
If anyone else can think of a better order of things, or would like
to start doing any of this before I get to it, please let me know.
--
I think that all good, right thinking people in this country are sick
and tired of being told that all good, right thinking people in this
country are fed up with being told that all good, right thinking
people
in this country are fed up with being sick and tired. I''m certainly
not, and I''m sick and tired of being told that I am.
-- Monty Python
---------------------------------------------------------------------
Luke Kanies | http://reductivelabs.com | http://madstop.com
On 3/28/07, Luke Kanies <luke@madstop.com> wrote:> Hi all, >[snip]> > Also, in general, I just want to make this clear: I am always > looking for help with the documentation, and I will not be offended > in the slightest if someone rewrites some or all of a given page, or > any of that. The whole point of having these docs on the wiki is so > the community can help with them. I''m a bit too close to the code > sometimes to see the user side well enough to document for it, and I > don''t do the best job of prioritizing on documenting vs. coding. I > *know* the existing docs aren''t very good, and I would greatly > appreciate help making them better. > > If you have an idea for better docs, please add that idea. If you > think docs are missing but you don''t think you can write it, please > create a MissingDocumentation page and add it there, then hopefully > someone else in the community can fill in the blanks. >I am just starting to implement Puppet at work and one of the things I noticed is that not all of the internal documentation (via Rdoc) has corresponding man pages or wiki pages. I mentioned this briefly in IRC the other day and I believe the response was that there isn''t a Markdown to ReST converter yet. I believe that man pages are essential to a tool targeted primarily to system administrators. And, having a tool that converts the API documentation ensures that the online documentation is in sync with the actual code. I noticed that there is already a ticket open for this, however, I''m not sure what progress has been made. If this particular effort has stalled, I''d like to at least get this discussion started again; though I certainly don''t want to take over anyone else''s work. If anyone else is working on this, please let me know so I can lend any resources that would be helpful. If not, I''d like to start working to make this happen. Regards, -David
--On Wednesday, March 28, 2007 1:35 PM -0500 Luke Kanies <luke@madstop.com> wrote:> I''d love to have a couple of semi-official documentation wranglers, > people who paid attention to how current the docs are with the code, > and who kept track of changes to the wiki to keep track of what > documents people are making the most changes to and hopefully use > that information to decide when a document should be rewritten.I''d love to help with that. That would make it easier for me to keep up with the language anyway.
I''d also like to help and am wondering if Trac offers something similar to Dokuwiki''s FIXME macro that can be used to easily identify areas in need of elaboration? If not, perhaps a simple prefix of ''Note by $person ...'' can be used. For example, I''ve already added a question to Luke''s new Introduction (nice work Luke!) but I''m just wondering how likely it is that others will see that the question is sitting there. Best, Adam -----Original Message----- From: puppet-users-bounces@madstop.com on behalf of Digant C Kasundra Sent: Wed 3/28/2007 10:43 PM To: Puppet User Discussion Subject: Re: [Puppet-users] Working on docs: PRM and modules --On Wednesday, March 28, 2007 1:35 PM -0500 Luke Kanies <luke@madstop.com> wrote:> I''d love to have a couple of semi-official documentation wranglers, > people who paid attention to how current the docs are with the code, > and who kept track of changes to the wiki to keep track of what > documents people are making the most changes to and hopefully use > that information to decide when a document should be rewritten.I''d love to help with that. That would make it easier for me to keep up with the language anyway. _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users _______________________________________________ Puppet-users mailing list Puppet-users@madstop.com https://mail.madstop.com/mailman/listinfo/puppet-users
On Mar 28, 2007, at 9:26 PM, David Narayan wrote:> I am just starting to implement Puppet at work and one of the things I > noticed is that not all of the internal documentation (via Rdoc) has > corresponding man pages or wiki pages. I mentioned this briefly in IRC > the other day and I believe the response was that there isn''t a > Markdown to ReST converter yet.There are two types of docs that are not in the wiki: The "reference" docs, which are generated from strings in the code using ''puppetdoc'', and the API docs, generated by RDoc. I don''t think it''ll ever be possible to convert the API docs to the wiki, and that probably doesn''t make sense. It won''t be hard to convert the reference docs to ReST (they''re currently in Markdown), and I''d be glad to help someone who wanted to do it. The main thing is that you have to understand how puppetdoc is collecting all of the documentation it generates -- from places like the types, providers, functions, reports, and the configuration parameters. As to how those relate to man pages... I don''t really know how to convert any of these to man pages, but certainly I would like to.> I believe that man pages are essential to a tool targeted primarily to > system administrators. And, having a tool that converts the API > documentation ensures that the online documentation is in sync with > the actual code.Do you really mean the API docs, or the reference docs? What would you convert them to?> I noticed that there is already a ticket open for this, however, I''m > not sure what progress has been made. If this particular effort has > stalled, I''d like to at least get this discussion started again; > though I certainly don''t want to take over anyone else''s work. If > anyone else is working on this, please let me know so I can lend any > resources that would be helpful. If not, I''d like to start working to > make this happen.I''d love it if you would start working on this. I don''t think much has been done, although Ben has made a couple of man pages for different Puppet executables (available from svn in the man/ directory). -- At my lemonade stand I used to give the first glass away free and charge five dollars for the second glass. The refill contained the antidote. -- Emo Phillips --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On Mar 29, 2007, at 9:18 AM, Kosmin, Adam wrote:> I''d also like to help and am wondering if Trac offers something > similar to Dokuwiki''s FIXME macro that can be used to easily > identify areas in need of elaboration? If not, perhaps a simple > prefix of ''Note by $person ...'' can be used. For example, I''ve > already added a question to Luke''s new Introduction (nice work > Luke!) but I''m just wondering how likely it is that others will see > that the question is sitting there.I think we''ll have to rely on convention here, but if someone can point to a way to do this, I''ll be glad to do what I can to enable it. I hope to get the translations plugin installed today. -- Honest criticism is hard to take, particularly from a relative, a friend, an acquaintance, or a stranger. -- Franklin P. Jones --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On Mar 28, 2007, at 9:43 PM, Digant C Kasundra wrote:> --On Wednesday, March 28, 2007 1:35 PM -0500 Luke Kanies > <luke@madstop.com> > wrote: > >> I''d love to have a couple of semi-official documentation wranglers, >> people who paid attention to how current the docs are with the code, >> and who kept track of changes to the wiki to keep track of what >> documents people are making the most changes to and hopefully use >> that information to decide when a document should be rewritten. > > I''d love to help with that. That would make it easier for me to > keep up > with the language anyway.Okay, great. I''ve created a Documentation Wranglers[1] page with you as the initial member. When can I start assigning documentation bugs to you? :) I figure we can start creating per-person pages, so I set it up to link to a page for you, and I''ll let you fill in the appropriate contact information for you. Anyone else who wants to be a doc wrangler, please add your name to the page and ping Digant so he knows you''ll be helping. I''ve also created a page for myself[2] on the wiki, and it''s probably a good idea if people started doing that so we can start making the community a bit more visible. 1 - https://reductivelabs.com/trac/puppet/wiki/DocumentationWranglers -- No one who cannot rejoice in the discovery of his own mistakes deserves to be called a scholar. --Donald Foster --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com
On 3/29/07, Luke Kanies <luke@madstop.com> wrote: [snip]> > There are two types of docs that are not in the wiki: The > "reference" docs, which are generated from strings in the code using > ''puppetdoc'', and the API docs, generated by RDoc. > > I don''t think it''ll ever be possible to convert the API docs to the > wiki, and that probably doesn''t make sense. >Well, certainly not as an editable page. I was thinking more along the lines of a readonly page just so all of the documentation (including the API doc) is together. However, I would consider work on the API docs a secondary goal to getting the reference docs available as man pages.> It won''t be hard to convert the reference docs to ReST (they''re > currently in Markdown), and I''d be glad to help someone who wanted to > do it. The main thing is that you have to understand how puppetdoc > is collecting all of the documentation it generates -- from places > like the types, providers, functions, reports, and the configuration > parameters. > > As to how those relate to man pages... I don''t really know how to > convert any of these to man pages, but certainly I would like to. >The reference docs are primarily what I was referring to. If they can be converted to ReST easily, great. I don''t know how to convert them to man pages yet -- but that''s what I''d like to start working on.> > I believe that man pages are essential to a tool targeted primarily to > > system administrators. And, having a tool that converts the API > > documentation ensures that the online documentation is in sync with > > the actual code. > > Do you really mean the API docs, or the reference docs? What would > you convert them to? >Sorry -- that paragraph was a bit unclear. As I was writing that, I was thinking of Perl and POD where there are converters for many different formats (e.g. Pod::Man, Pod::Usage, etc.). In a similar vein I was thinking of working on something akin to Rdoc::Man. And in conjunction with that thought, the availability of such a tool would allow the documentation to be easily converted to man pages or other formats. Initially I think I will focus on the reference docs but perhaps the API docs will not be as difficult once the initial work is complete. [snip]> > I''d love it if you would start working on this. I don''t think much > has been done, although Ben has made a couple of man pages for > different Puppet executables (available from svn in the man/ directory). >Thanks for the pointer. I''ll start working on this and see what I can come up with. -David
On Mar 29, 2007, at 3:44 PM, David Narayan wrote:> > Well, certainly not as an editable page. I was thinking more along the > lines of a readonly page just so all of the documentation (including > the API doc) is together. However, I would consider work on the API > docs a secondary goal to getting the reference docs available as man > pages.This is one of my big problems with RDoc -- it''s not a common format, so no other site can handle it. I wish they''d just picked an existing format, instead of making up a new one.> The reference docs are primarily what I was referring to. If they can > be converted to ReST easily, great. I don''t know how to convert them > to man pages yet -- but that''s what I''d like to start working on.That would be *great*. For the record, once you''ve got ReST, you can get Tex, and from there you can get anything. I write all of my contracts and articles in ReST, and convert them to pdf with the following code: rst2latex file.rst > file.tex texi2pdf file.tex > /dev/null You can just as easily convert tex to nroff or troff or whatever it is that ''man'' expects.> Sorry -- that paragraph was a bit unclear. As I was writing that, I > was thinking of Perl and POD where there are converters for many > different formats (e.g. Pod::Man, Pod::Usage, etc.). In a similar vein > I was thinking of working on something akin to Rdoc::Man. And in > conjunction with that thought, the availability of such a tool would > allow the documentation to be easily converted to man pages or other > formats.Yeah, this would be nice, but from what I can tell, RDoc wasn''t written as abstractly as Pod was. Dave Thomas wrote the RDoc::usage stuff on my recommendation, but I''m not real fond of it, not least because it doesn''t behave like a man page at all.> Initially I think I will focus on the reference docs but perhaps the > API docs will not be as difficult once the initial work is complete.Sounds good to me.>> I''d love it if you would start working on this. I don''t think much >> has been done, although Ben has made a couple of man pages for >> different Puppet executables (available from svn in the man/ >> directory). >> > > Thanks for the pointer. I''ll start working on this and see what I can > come up with.All of these conversions will involve commits to svn, since you''ll be changing the code itself (well, mostly strings inside the code). If you give me your user account on trac, I''ll copy the auth info over to the svn auth file and set you up with commit access. -- To define recursion, we must first define recursion. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com