I must say that the HBASE site is just awesome! They even have multi language support for documentation.
On 7/11/13 2:34 PM, "Jay Kreps" <jay.kr...@gmail.com> wrote: >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 >> >> >> >>
