-1 on no docs no submits. Docs are important to people that need a contribution they didn't write themselves. The first ones are the ones to write docs where missing. You contribute because you need code, not because you need docs on it.
On Thu, Sep 5, 2013 at 9:25 AM, Giles Sirett <giles.sir...@shapeblue.com> wrote: > +1 on "no docs, no submit" > > Kind Regards > Giles > > D: +44 20 3603 0541 | M: +44 796 111 2055 > giles.sir...@shapeblue.com > > > > > -----Original Message----- > From: Sebastien Goasguen [mailto:run...@gmail.com] > Sent: 05 September 2013 07:14 > To: dev@cloudstack.apache.org > Cc: aemne...@gmail.com > Subject: Re: documentation/wiki is a mess > > > 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 >> > > This email and any attachments to it may be confidential and are intended > solely for the use of the individual to whom it is addressed. Any views or > opinions expressed are solely those of the author and do not necessarily > represent those of Shape Blue Ltd or related companies. If you are not the > intended recipient of this email, you must neither take any action based upon > its contents, nor copy or show it to anyone. Please contact the sender if you > believe you have received this email in error. Shape Blue Ltd is a company > incorporated in England & Wales. ShapeBlue Services India LLP is operated > under license from Shape Blue Ltd. ShapeBlue is a registered trademark.
