-Re: Make documentation part of new features acceptance criteria?
Jay Kreps 2013-07-11, 21:35
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.
On Thu, Jul 11, 2013 at 2:47 AM, Cosmin Lehene <[EMAIL PROTECTED]> 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.
> On 7/10/13 7:15 PM, "Jay Kreps" <[EMAIL PROTECTED]> 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
> >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
> >it with the code because the code is in git and Apache only allows SVN as
> >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
> >should. We can certainly apply it to the final 0.8 release if people are
> >On Wed, Jul 10, 2013 at 1:17 AM, Cosmin Lehene <[EMAIL PROTECTED]> 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
> >> Also, having this type of documentation as part of the codebase to allow
> >> proper versioning might be a good idea as well.
> >> Cosmin