On Thu, Apr 4, 2013 at 12:39 PM, Chip Childers <chip.child...@sungard.com>wrote:
> On Thu, Apr 04, 2013 at 02:33:23PM -0500, Joe Brockmeier wrote: > > On Thu, Apr 4, 2013, at 10:34 AM, Radhika Puthiyetath wrote: > > > We do have functional spec. What exactly are we demanding for ? > > > > Ideally something that actually gives a "how to use this feature" > > bare-bones framework to write docs off of. If the FS takes care of that, > > that's fine - but I'm not sure that the FSes are being updated after a > > feature has landed with a "here's some guidance on actually *using* the > > feature." > > > > It's fine by me if we ask for the FS to be updated with this as the > > feature lands into master, rather than having a separate README. > > +1 to updating the FS with usage details. That helps with both docs, > and to make the FS useful for a reference in the future (i.e.: reflects > the implementation of the design, not the design before the > implementation). > > Just to confirm, it sounds like we are agreeing as a community that a feature should not be "blocked" from release even if it isn't mentioned in the /docs directory. Is that correct? I'm not convinced about creating an additional category of documents called READMEs. One question I had about that concept: where would we publish them? If on the wiki, then the info might as well be inside the FS. If the READMEs are published on a blog, like a series of short articles "Featured New Feature of the Week," then that might be very cool actually. For the features I've worked on, most of the contributors are already writing very good specs, including usage info. For the eng contributors who for whatever reason won't be putting docs directly into the /docs directory, having a great FS is always useful. Just +1 to keeping that up! Jessica T. > > > > -----Original Message----- > > > From: Joe Brockmeier [mailto:j...@zonker.net] > > > Sent: Thursday, April 04, 2013 8:49 PM > > > To: dev@cloudstack.apache.org > > > Subject: Re: [DOCS] More OSS writers needed > > > > > > On Thu, Apr 4, 2013, at 10:05 AM, Chip Childers wrote: > > > > We discussed this in the March 20 IRC meeting [1] (see the "# 4. > > > > Active Feature > > > > Release: Docs Status #" section). If someone wants to propose this > as > > > > a feature merge requirement, I'd +1 it. As long as we're not being > > > > too onerous about it, even simple descriptions help. > > > > > > Argh. My bad. I'll send that out today. And yes, all I would ask is a > > > simple readme that doc authors can work off of. > > > > > > Best, > > > > > > jzb > > > -- > > > Joe Brockmeier > > > j...@zonker.net > > > Twitter: @jzb > > > http://www.dissociatedpress.net/ > > > > > > Best, > > > > jzb > > -- > > Joe Brockmeier > > j...@zonker.net > > Twitter: @jzb > > http://www.dissociatedpress.net/ > > >
