> Doesn't this make it a bit harder for the average user to know what public > API is?
Possibly, its hard to know w/o data. I am not convinced the readme is better place for new devs to find this critical piece of information. My thinking was that javadoc is something that developers read in their IDE, therefore its important we define the API there. I had two goals for this javadoc that I thought new developers were likely to read: * Define the public API * Help new developers find other top level API entry points > the README is also for consumers of the binary tarball... which does not > contain the Accumulo.java file Thats a good point. Based on these comments I think the following would be a better solution than defining the API in Readme.md or Accumulo.java. * Define the API on the website at a place where it has a stable link, like https://accumulo.apache.org/api. * Link to this definition from README.md, Accumulo.java, Accumulo Tour, Accumulo User manual, and any other docs written for developers. I took a quick look at the tour and the user manual section on writing clients and did not see mention of the API. We could make all of these places link to the README on github, but I think linking to https://accumulo.apache.org/api is more elegant. This way we can avoid trying to decide the one place that would be most beneficial to place this info, instead link to it from any documentation written for new developers. [ Full content available at: https://github.com/apache/accumulo/pull/656 ] This message was relayed via gitbox.apache.org for [email protected]
