[chef] Re: Re: Re: Re: Documenting Cookbooks

[Mike < >]

> It would suck to have to write documentation twice. :)

Absolutely true.

So I think the root question is: Where should a cookbook's
documentation live? In its entirety in the README? [1] or in a doc/
directory, like many other software projects, or hell, in the
metadata.rb [2]?

I think a README is a great place to say "hey, here's the thing,
here's some basics, check out the documentation for further details".
It's the Step 1 of using a cookbook, read the README.

Should the README be a comprehensive manual of everything in this
cookbook? I think not. Document the code in the code.

And until Chef Server has _anything_ to do with attributes in
metadata.rb, they are just "spam" and non-canonical, duplicated
attributes that may fall from accuracy/sync as time goes by.

I'm going to look at promoting/working with yard-chef more to achieve
the approach of documentation in the source, which renders html on the
side.

Curious to hear if there are other approaches that are being used.

-Mike

[1]: https://github.com/opscode-cookbooks/apache2/blob/master/README.md
- 582 lines long!
[2]: https://github.com/opscode-cookbooks/apache2/blob/master/metadata.rb

On Wed, Apr 3, 2013 at 9:51 AM, John Alberts 
<
 >
 wrote:
>
> On Wed, Apr 3, 2013 at 8:30 AM, Dimitri Aivaliotis 
> <
 >
> wrote:
>>
>> Both tools could be used on the same cookbook in a
>> complementary fashion: knife-cookbook-doc to generate the README and
>> yard-chef to generate browsable docs with your choice of template.
>
>
> I've never used Yard before.  Is the syntax for Yard the same as this
> knife-cookbook-doc plugin?  It would suck to have to write documentation
> twice. :)
>
>
>
> --
> John Alberts