Cool, let's do that then. I think we will likely be in a better state in a week--Sriram is working on updating the design page which is the last big outstanding thing that is out of date.
I do totally love the hbase documentation, they are doing it right. -Jay On Thu, Jul 11, 2013 at 2:47 AM, Cosmin Lehene <cleh...@adobe.com> wrote: > I like the release criteria idea. Perhaps add them to coding guide or the > developer section on wiki? > > WRT feature completeness, I didn't think about having a doc for each one, > but rather updating the existing doc or the CHANGES.txt file (we don't > have one yet) with a note when adding new configurations, new interfaces > or new tools. > I think should be an awareness thing mostly. > Kafka's documentation is actually pretty decent, otherwise and the Coding > Guidelines are great. > > I'm not sure if this would work for Kafka or not but you may want to look > at http://hbase.apache.org/book.html for an example of documentation which > gets versioned with the code. > > Cosmin > > > > > > > On 7/10/13 7:15 PM, "Jay Kreps" <jay.kr...@gmail.com> wrote: > > >I like the idea of improving our documentation. Help is very much > >appreciated in this area (but of course the problem is that the people who > >experience the holes almost by definition can't fill them in). So even > >just > >pointing out areas that aren't covered is really helpful. > > > >We are in a sort of awkward stage this week because we have a 0.8 beta > >release but no detailed docs on its internals. > > > >WRT your specific proposals. I don't think we should do the documentation > >with each feature because I think that tends to lead to a bunch of little > >documents one for each change. I think we effectively get this out of > >JIRA+wiki today. This usually serves as a fairly complete design doc + > >commentary be others. It is pretty hard to get information out of this > >format for a new user, though. > > > >We do version control documentation but we can't physically version > >control > >it with the code because the code is in git and Apache only allows SVN as > >a > >mechanism for publishing to xxx.apache.org. :-( > > > >Instead what about this: we add a new release criteria for documentation > >completeness. It would be good to formalize the release criteria anyway. > >Informally they are something like > >1. Developers think it is feature complete > >2. Unit tests pass > >3. Integration/stress tests pass > >4. Some production usage > >It would be good to add to this list (5) documentation up-to-date and not > >do a release without this. > > > >It is debatable whether this should apply to beta releases, but probably > >it > >should. We can certainly apply it to the final 0.8 release if people are > >on > >board. > > > >-Jay > > > > > > > >On Wed, Jul 10, 2013 at 1:17 AM, Cosmin Lehene <cleh...@adobe.com> wrote: > > > >> I'm not sure if there's already a guideline like this, but I wouldn't it > >> make sense to have it in order to keep documentation in sync with the > >>code? > >> Also, having this type of documentation as part of the codebase to allow > >> proper versioning might be a good idea as well. > >> > >> Cosmin > >> > >
