You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@kafka.apache.org by Cosmin Lehene <cl...@adobe.com> on 2013/07/10 10:17:50 UTC
Make documentation part of new features acceptance criteria?
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
Re: Make documentation part of new features acceptance criteria?
Posted by Jun Rao <ju...@gmail.com>.
Cosmin,
That's a good idea. In the past, for major new features, we tend to create
a wiki page to outline the design. The wiki pages can be organized better.
Is this what you are looking for?
Thanks,
Jun
On Wed, Jul 10, 2013 at 1:17 AM, Cosmin Lehene <cl...@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
>
Re: Make documentation part of new features acceptance criteria?
Posted by Sriram Subramanian <sr...@linkedin.com>.
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" <ja...@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 <cl...@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" <ja...@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 <cl...@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
>> >>
>>
>>
Re: Make documentation part of new features acceptance criteria?
Posted by Jay Kreps <ja...@gmail.com>.
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 <cl...@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" <ja...@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 <cl...@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
> >>
>
>
Re: Make documentation part of new features acceptance criteria?
Posted by Cosmin Lehene <cl...@adobe.com>.
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" <ja...@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 <cl...@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
>>
Re: Make documentation part of new features acceptance criteria?
Posted by Jay Kreps <ja...@gmail.com>.
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 <cl...@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
>