On Sep 5, 2013, at 1:11 AM, Prasanna Santhanam <t...@apache.org> wrote:
> Radhika, what I meant was everyone should help out with docs. Esp. > those working on a feature should care most that the docs for their > feature is perfect for an end user to understand, implement and use. > > We shouldn't piggy-back on those helping fix doc bugs all the time > which I see happening too often. Someone files a doc bug and someone > else fixes it and someone else reviews it and finally the users are > still having trouble understanding it. We're just creating work for > ourselves that way. > > Feature specs have architectural and implementation details and may > not often be fully baked by the time the feature starts development. > Changes happen during implementation and reviewing our docs after > everything is merged is a good forcing-function to fix our docs. > > I'm +1 for style guides and markdown based docs. They should make this > whole process a lot easier for everyone. I am a big +1 for literally forcing devs to submit docs for user facing features, otherwise the feature does not get added. Just like unit tests. No unitests, no commit, no docs, no commit. The devs are the best to write the docs of their own feature. > > On Wed, Sep 04, 2013 at 09:52:03PM -0700, Ahmad Emneina wrote: >> I think prasanna hit the nail on the head. I'm sure there are features >> there no one knows about, or ever will... >> +1 for developers documenting what features/functions are abound. >> >> >> >> On Wed, Sep 4, 2013 at 9:36 PM, Radhika Puthiyetath < >> radhika.puthiyet...@citrix.com> wrote: >> >>> Hi, >>> >>> We do not have a doc team as such :-) >>> >>> We have a set of doc contributors that so far have not worked as a team. >>> Probably, we should think about aligning the doc efforts and having a >>> process and style guide in place. >>> >>> If the FS is good enough, we need not trouble the code committers to write >>> own docs is what I feel. >>> >>> Regards >>> -Radhika >>> >>> -----Original Message----- >>> From: Prasanna Santhanam [mailto:t...@apache.org] >>> Sent: Thursday, September 05, 2013 9:34 AM >>> To: dev@cloudstack.apache.org >>> Subject: Re: documentation/wiki is a mess >>> >>> On Tue, Sep 03, 2013 at 11:10:28AM -0700, Darren Shepherd wrote: >>>> >>>> The state of documentation of an open source projects says a lot about >>>> the community that develops it... >>>> >>> >>> Esp. for XML documentation: I say we write our own docs if we want our >>> feature to be used. Or it dies a natural death in quiet isolation with no >>> one ever using it. Docs team can handle the editing and organizing bits. >>> That should go for Wikis too. If you want the wiki to be useful then write >>> it, organize it and maintain it. Don't just put it there to fill a >>> template. It'll never recieve any love. >>> >>> -- >>> Prasanna., >>> >>> ------------------------ >>> Powered by BigRock.com >>> >>> > > -- > Prasanna., > > ------------------------ > Powered by BigRock.com >
