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 >>
