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.

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

I like the idea of improving our documentation. Help is very muchappreciated in this area (but of course the problem is that the people whoexperience the holes almost by definition can't fill them in). So even justpointing 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 betarelease but no detailed docs on its internals.

WRT your specific proposals. I don't think we should do the documentationwith each feature because I think that tends to lead to a bunch of littledocuments one for each change. I think we effectively get this out ofJIRA+wiki today. This usually serves as a fairly complete design doc +commentary be others. It is pretty hard to get information out of thisformat for a new user, though.

We do version control documentation but we can't physically version controlit with the code because the code is in git and Apache only allows SVN as amechanism for publishing to xxx.apache.org. :-(

Instead what about this: we add a new release criteria for documentationcompleteness. It would be good to formalize the release criteria anyway.Informally they are something like1. Developers think it is feature complete2. Unit tests pass3. Integration/stress tests pass4. Some production usageIt would be good to add to this list (5) documentation up-to-date and notdo a release without this.

It is debatable whether this should apply to beta releases, but probably itshould. We can certainly apply it to the final 0.8 release if people are onboard.

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

I like the release criteria idea. Perhaps add them to coding guide or thedeveloper 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'thave one yet) with a note when adding new configurations, new interfacesor new tools.I think should be an awareness thing mostly.Kafka's documentation is actually pretty decent, otherwise and the CodingGuidelines are great.

I'm not sure if this would work for Kafka or not but you may want to lookat http://hbase.apache.org/book.html for an example of documentation whichgets versioned with the code.

CosminOn 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>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 <[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>>code?>> Also, having this type of documentation as part of the codebase to allow>> proper versioning might be a good idea as well.>>>> Cosmin>>

> 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" <[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> >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 <[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> >>code?> >> Also, having this type of documentation as part of the codebase to allow> >> proper versioning might be a good idea as well.> >>> >> Cosmin> >>>>

NEW: Monitor These Apps!

All projects made searchable here are trademarks of the Apache Software Foundation.
Service operated by Sematext