"Gabriel - IP Guys" <[email protected]> writes:
> "Gabriel - IP Guys" <[email protected]> writes:
>> [Mr Gabriel Says ...]
>>> +1 - It seems that some work has already been done to make a standard,
This would have been so much easier if you used standard quoting rather than
the custom "[Mr Gabriel Says]" stuff, or just top-posted. :)
Anyway, I fixed the quotation by hand this time, but I would honestly have
preferred top-quoting. It would have been less hard work.
>>> write scripts, and automate stuff!), but it would be nice to get a little
>>> traction in this area. If I have to bug that cr*p out of the module writers,
>>> then that's something I'm prepared to do.
>>
>> You would probably get better results, generally speaking, by ensuring that
>> there are good, standard documents about how to do this visible to community
>> members.
>
> Are you suggesting that I publish a quick document on how to do a readme?
Yup. (Among other things that should be in the document. :)
> A document, on how to write a document? Well, if that what it takes to get
> people working from the same page, then sure I'll do it.
How else do you expect people to know what they should be doing to structure
the document? Unless you can tell someone how to do it before they write
their documentation (and we ever hear from them), they would have to re-write
stuff to conform to the standard otherwise. :)
> (Didn't I do that with the example posting? Maybe a blog post to go with it
> would help - Or an open posting to this list? Ideas?
I would strongly suggest you look to get it integrated with the other "how to
write a module" documentation. See, for example, the existing puppet
documentation and all, or the perlmodstyle guide, for how these flow.
This post is great, but in two weeks who will ever see it? A blog is the same
thing, ephemeral. Sure, great posts get referenced for a while, but they
don't live as long as real documentation.
> To be honest with you, I don't see what is so hard to grasp, it's just one
> more point on the checklist before releasing a module, take 20 seconds to
> write a README that explains how to use this module, where it came from, and
> who made it.
Ah, but you don't just want that, you want them to follow a reasonable style,
to include certain details, and so forth. Also, you wanted to be successful
at doing that. ;)
[...]
> Developing a standard is fine, and I'll 'vote' for that anyday of the week,
> but this is a request to help those coming into this community.
You have no obligation to do anything. I tell you, though, that if you don't
go ahead and put in the work — and no one else does either — I would put money
on the fact that this doesn't happen.
Good programing practices, and communities, don't happen in a vacuum. This
is a chance you have to help one happen, but you (naturally) have no
obligation.
(Also, obviously, this is /my opinion/ about what will help. :)
[...]
> Look to be honest, we just need a few module writers to begin to adopt using
> a basic readme format for their modules.
My essential point is that this is a nice idea, but you will get better
results doing something a bit more formal. In my experience, obviously.
> I'll put my neck on the line, and say I'll the write the damn readmes if you
> want!
Personally, I don't care that much. It would be nice, and probably help the
puppet community, but I haven't the time to write the standards or push for it
right now.
Now, if you *do* put in the work then, hey, you get to set the standard.
> ...... Actually, I think that's what this needs - Talk is cheap, action is
> priceless
*nod*
Daniel
--
✣ Daniel Pittman ✉ [email protected] ☎ +61 401 155 707
♽ made with 100 percent post-consumer electrons
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" 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-users?hl=en.
