Re: Require projects to have solid API docs

2015-10-12 Thread Greg Stein 
On Sun, Oct 11, 2015 at 11:20 PM, Julian Hyde  wrote:

> On Sun, Oct 11, 2015 at 1:11 PM, Alan D. Cabrera 
> wrote:
> > Should != Must
>
> Yes, I know. But I didn't want to have everyone leap into yet another
> long-winded debate with no one even having mentioned that there is
> existing policy on this matter.
>

Euh... no. ComDev does *not* set/create policy for the ASF. The page you
cited is not Foundation policy.

Cheers,
-g

Re: Require projects to have solid API docs

2015-10-12 Thread Emmanuel Lécharny 
Le 11/10/15 17:59, Andrew Pennebaker a écrit :
> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.

I'm ok with this proposal, when we have checked that every TLP has a
decent API documentation...

Good luck with that ;-)

/me guilty as charged...


-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Require projects to have solid API docs

2015-10-11 Thread Andrew Pennebaker 
In the future, could Apache Incubator require projects to maintain better
API documentation before graduation? In particular, Kafka has rather sparse
documentation in v0.8. The Javadocs appear to be randomly hosted on this or
that professor webpage, and no Kafka javadoc has documentation for
*both* Consumers
and Producers.

-- 
Cheers,
Andrew

Re: Require projects to have solid API docs

2015-10-11 Thread Julian Hyde 
Per [1], "Apache projects should provide sufficient documentation [… so that … 
] users can both make use of our software freely”.

And: "users of Apache software should be able to find our software, learn how 
to use it, and actually apply it to all its common use cases solely by going to 
the Apache project’s own website”.

So: there should be some documentation about how to use the project on the 
project web site. That documentation does not need to be in any particular 
form, such as javadoc.

Julian

[1] https://community.apache.org/projectIndependence.html


> On Oct 11, 2015, at 9:29 AM, Luciano Resende  wrote:
> 
> On Sun, Oct 11, 2015 at 9:15 AM, Ross Gardler 
> wrote:
> 
>> No. That’s not the role of the foundation. However, ensuring people
>> contributing to the docs are recognized like any other contributor is the
>> role of the foundation. Can you help contribute to such docs?
>> 
>> 
>> 
> +1
> 
> -- 
> Luciano Resende
> http://people.apache.org/~lresende
> http://twitter.com/lresende1975
> http://lresende.blogspot.com/


-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Re: Require projects to have solid API docs

2015-10-11 Thread Luciano Resende 
On Sun, Oct 11, 2015 at 9:15 AM, Ross Gardler 
wrote:

> No. That’s not the role of the foundation. However, ensuring people
> contributing to the docs are recognized like any other contributor is the
> role of the foundation. Can you help contribute to such docs?
>
>
>
+1

-- 
Luciano Resende
http://people.apache.org/~lresende
http://twitter.com/lresende1975
http://lresende.blogspot.com/

RE: Require projects to have solid API docs

2015-10-11 Thread Ross Gardler 
No. That’s not the role of the foundation. However, ensuring people 
contributing to the docs are recognized like any other contributor is the role 
of the foundation. Can you help contribute to such docs?



Sent from Outlook Mail<http://go.microsoft.com/fwlink/?LinkId=550987> for 
Windows 10 phone





From: Andrew Pennebaker
Sent: Sunday, October 11, 2015 8:59 AM
To: general@incubator.apache.org
Subject: Require projects to have solid API docs


In the future, could Apache Incubator require projects to maintain better
API documentation before graduation? In particular, Kafka has rather sparse
documentation in v0.8. The Javadocs appear to be randomly hosted on this or
that professor webpage, and no Kafka javadoc has documentation for
*both* Consumers
and Producers.

--
Cheers,
Andrew

Re: Require projects to have solid API docs

2015-10-11 Thread Mark Thomas 
On 11/10/2015 16:59, Andrew Pennebaker wrote:
> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.

No.

It is not the role of the incubator to assess the *quality* of the code
or any other release artefact.

Graduation from the incubator is based on the quality of the community.
This is because a good community can always (and usually does) turn
around bad code. Good code will never save a poor community.

If you have an issue with a project's release artefacts, open a bug
report. Better still, open a bug report and provide a patch/pull request
with a fix.

Mark

-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Re: Require projects to have solid API docs

2015-10-11 Thread Alan D. Cabrera 
Should != Must


Regards,
Alan

> On Oct 11, 2015, at 11:49 AM, Julian Hyde  wrote:
> 
> Per [1], "Apache projects should provide sufficient documentation [… so that 
> … ] users can both make use of our software freely”.
> 
> And: "users of Apache software should be able to find our software, learn how 
> to use it, and actually apply it to all its common use cases solely by going 
> to the Apache project’s own website”.
> 
> So: there should be some documentation about how to use the project on the 
> project web site. That documentation does not need to be in any particular 
> form, such as javadoc.
> 
> Julian
> 
> [1] https://community.apache.org/projectIndependence.html
> 
> 
>> On Oct 11, 2015, at 9:29 AM, Luciano Resende  wrote:
>> 
>> On Sun, Oct 11, 2015 at 9:15 AM, Ross Gardler 
>> wrote:
>> 
>>> No. That’s not the role of the foundation. However, ensuring people
>>> contributing to the docs are recognized like any other contributor is the
>>> role of the foundation. Can you help contribute to such docs?
>>> 
>>> 
>>> 
>> +1
>> 
>> -- 
>> Luciano Resende
>> http://people.apache.org/~lresende
>> http://twitter.com/lresende1975
>> http://lresende.blogspot.com/
> 
> 
> -
> To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
> For additional commands, e-mail: general-h...@incubator.apache.org
> 


-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Re: Require projects to have solid API docs

2015-10-11 Thread Julian Hyde 
On Sun, Oct 11, 2015 at 1:11 PM, Alan D. Cabrera  wrote:
> Should != Must

Yes, I know. But I didn't want to have everyone leap into yet another
long-winded debate with no one even having mentioned that there is
existing policy on this matter.

Julian

-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Re: Require projects to have solid API docs

2015-10-11 Thread Alan D. Cabrera 

> On Oct 11, 2015, at 9:20 PM, Julian Hyde  wrote:
> 
> On Sun, Oct 11, 2015 at 1:11 PM, Alan D. Cabrera  wrote:
>> Should != Must
> 
> Yes, I know. But I didn't want to have everyone leap into yet another
> long-winded debate with no one even having mentioned that there is
> existing policy on this matter.

:)



-
To unsubscribe, e-mail: general-unsubscr...@incubator.apache.org
For additional commands, e-mail: general-h...@incubator.apache.org

Re: Require projects to have solid API docs

2015-10-11 Thread Joe Stein 
The Apache Kafka javadoc and scala doc are published with source and
binaries https://archive.apache.org/dist/kafka/0.8.2.2/ and they can be
generated from source.

There is no javadoc for both producer and consumer (yet but you can
generate from trunk for 0.9) because the new java consumer has been in
development with testing underway now. If you want to consume from Kafka
(as stable) using the project client you have to use the Scala consumer.

There is a lot of documentation especially around the API
http://kafka.apache.org/documentation.html#api with lots of good links if
any issues github PR are accepted now.

For more kafka questions feel free to reach out to the community
http://kafka.apache.org/contact.html.

Thanks!

~ Joe Stein


~ Joe Stein

On Sun, Oct 11, 2015 at 11:59 AM, Andrew Pennebaker <
andrew.penneba...@gmail.com> wrote:

> In the future, could Apache Incubator require projects to maintain better
> API documentation before graduation? In particular, Kafka has rather sparse
> documentation in v0.8. The Javadocs appear to be randomly hosted on this or
> that professor webpage, and no Kafka javadoc has documentation for
> *both* Consumers
> and Producers.
>
> --
> Cheers,
> Andrew
>