PROPOSAL: Standardize on including a reference to attributes/default.rb in README

[Jay Pipes]

Let's face it ... documenting attributes is a pain in the ass.

Documenting attributes TWICE -- once where the attribute default is defined and once in the README -- is a bigger pain in the ass.

I propose we adopt as a standard what the https;//github.com/stackforge/cookbookopenstack-common  README does, which is this:

Please see the extensive inline documentation in attributes/default.rb for descriptions of all the settable attributes for this cookbook.

Note that all attributes are in the default["openstack"] "namespace"

and be done with the duplication once and for all.

That way, if we see someone add a new attribute to a cookbook, we can say "hey, make sure you put documentation in the attributes/default.rb that clearly describes what this attribute does" and not have to worry about the README getting out of sync...

Who's with me?

-jay

[John Dewey]

Documenting attribute files, feels like rspec mocking (I end up writing the reverse of my code :)).  I personally think the README has a lot of unnecessary things in there.  Which templates are in the cookbook, which cookbooks are dependencies, which distros the cookbook is valid on, etc…   This stuff belongs in metadata.rb,  I see no point to duplicate those things in the README.

++ to Jay's suggestion.

--
You received this message because you are subscribed to the Google Groups "opscode-chef-openstack" group.
To unsubscribe from this group and stop receiving emails from it, send an email to opscode-chef-open...@googlegroups.com.
To post to this group, send email to opscode-che...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/opscode-chef-openstack/d80d5eb9-268e-468c-92bd-b4bc123aa791%40googlegroups.com?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Jesse Nelson]

I think there is a happy place where you can document the "important" few things that make a difference in the README, and then point @ the file for the "complete set" 

Another option is to use a doc generator

https://github.com/realityforge/knife-cookbook-doc

https://github.com/rightscale/yard-chef

  

I like the idea of using a document generator for this stuff. 

To view this discussion on the web visit https://groups.google.com/d/msgid/opscode-chef-openstack/52E9E304DC52433898B112DDEADF4C0C%40gmail.com?hl=en.

[Abel Lopez]

+1

--

[Matt Ray]

I agree with both of you. The README's seem to be on a path of excessive verbosity, the Description, Recipes and Resources (including examples of usage) are the essentials in my opinion. Dependencies and attributes are provided by the metadata, so let's try to reduce redundant documentation because it eventually gets stale.

Thanks,

Matt Ray

Senior Technical Evangelist :: Opscode

512.731.2218 :: ma...@opscode.com

mattray :: GitHub :: IRC :: Twitter

---

From: opscode-che...@googlegroups.com on behalf of John Dewey
Sent: Wednesday, June 05, 2013 10:39 PM
To: opscode-che...@googlegroups.com
Subject: Re: [chef-openstack] PROPOSAL: Standardize on including a reference to attributes/default.rb in README

 

To view this discussion on the web visit https://groups.google.com/d/msgid/opscode-chef-openstack/52E9E304DC52433898B112DDEADF4C0C%40gmail.com?hl=en.

[Ionuț Arțăriși]

On 06/06/2013 06:20 AM, Jesse Nelson wrote:
> I think there is a happy place where you can document the "important"
> few things that make a difference in the README, and then point @ the
> file for the "complete set"
>
> Another option is to use a doc generator
>
> https://github.com/realityforge/knife-cookbook-doc
> https://github.com/rightscale/yard-chef
> I like the idea of using a document generator for this stuff.
>

I agree with everyone :). It would be cool to only have to maintain the
code and not the README, but at the same time the README is much easier
to read and it's the "front page" of the recipes. If I was just a user
of the recipes I would really hate it if I would have to browse around
the metadata and attributes and recipe files for docs.

So a doc generator would be really cool to have.

-Ionuț

[Jay Pipes]

OK, community, I have created a bug report to track this feature:

https://bugs.launchpad.net/openstack-chef/+bug/1188777

It's marked low-hanging-fruit. If any new contributors out there would
like to get their feet wet with a contribution with a pretty defined
scope, this is a good one.

If you are unfamiliar with the contribution process, see my blog post
[1] and come hang out and ask questions on Freenode #openstack-chef channel.

Best,
-jay

[1]
http://www.joinfu.com/2013/05/working-with-the-openstack-code-review-and-ci-system-chef-edition/