I wanted to ask how people feel about a policy where an issue is notclosed until documentation has been added to the Wiki?

Problematic issues fall roughly in two categories:* They have a generic title (add UDF for XY) an attached patch and afew code reviews without ever even mentioning what the name or usageof the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)

* They have a design document or description with the intended syntaxbut that's often not the final form so one has to look up the patch(can't find a good example right now)

Both are a lot of work to document for someone who has not followedthat issue. Tracking undocumented things would be got to not forgetabout it and to have an incentive to do it.

Obviously not all things need documentation, and not all things needto be documented by the person who submitted the patch. But to makethings easier for documentation people it'd be great if the issuecould contain an up to date description of at least the syntax changesand configuration options etc. so that we can tidy it up and transferit to the wiki. It's not nice to dig through patches for this.

Another alternative would be to open issues like "Document HIVE-5252"but I like the other option better.

> Hi,>> I wanted to ask how people feel about a policy where an issue is not> closed until documentation has been added to the Wiki?>> Problematic issues fall roughly in two categories:> * They have a generic title (add UDF for XY) an attached patch and a> few code reviews without ever even mentioning what the name or usage> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)>> * They have a design document or description with the intended syntax> but that's often not the final form so one has to look up the patch> (can't find a good example right now)>> Both are a lot of work to document for someone who has not followed> that issue. Tracking undocumented things would be got to not forget> about it and to have an incentive to do it.>> Obviously not all things need documentation, and not all things need> to be documented by the person who submitted the patch. But to make> things easier for documentation people it'd be great if the issue> could contain an up to date description of at least the syntax changes> and configuration options etc. so that we can tidy it up and transfer> it to the wiki. It's not nice to dig through patches for this.>> Another alternative would be to open issues like "Document HIVE-5252"> but I like the other option better.>> What do people think?>> Cheers,> Lars>

-- CONFIDENTIALITY NOTICENOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.

There is no guarantee that the subtask will ever get completed afterthe feature goes in. There is no point of new features if users can'tactually figure how to use it.I think we should either add sufficient documentation in the releasenotes section of jira or add doc in wiki as upcoming feature before wecommit the changes.On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <[EMAIL PROTECTED]> wrote:> I think opening a separate doc ticket and making it a subtask of the dev> ticket works pretty well. The subtask can contain notes specific to> documentation.>> Eugene>>>> On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]>wrote:>>> Hi,>>>> I wanted to ask how people feel about a policy where an issue is not>> closed until documentation has been added to the Wiki?>>>> Problematic issues fall roughly in two categories:>> * They have a generic title (add UDF for XY) an attached patch and a>> few code reviews without ever even mentioning what the name or usage>> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)>>>> * They have a design document or description with the intended syntax>> but that's often not the final form so one has to look up the patch>> (can't find a good example right now)>>>> Both are a lot of work to document for someone who has not followed>> that issue. Tracking undocumented things would be got to not forget>> about it and to have an incentive to do it.>>>> Obviously not all things need documentation, and not all things need>> to be documented by the person who submitted the patch. But to make>> things easier for documentation people it'd be great if the issue>> could contain an up to date description of at least the syntax changes>> and configuration options etc. so that we can tidy it up and transfer>> it to the wiki. It's not nice to dig through patches for this.>>>> Another alternative would be to open issues like "Document HIVE-5252">> but I like the other option better.>>>> What do people think?>>>> Cheers,>> Lars>>>> --> CONFIDENTIALITY NOTICE> NOTICE: This message is intended for the use of the individual or entity to> which it is addressed and may contain information that is confidential,> privileged and exempt from disclosure under applicable law. If the reader> of this message is not the intended recipient, you are hereby notified that> any printing, copying, dissemination, distribution, disclosure or> forwarding of this communication is strictly prohibited. If you have> received this communication in error, please contact the sender immediately> and delete it from your system. Thank You.

-- CONFIDENTIALITY NOTICENOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.

Could a new status such as "Just needs doc" be added? Or perhaps aresolution such as "Undocumented"? Because folks who want to get theirhands on new features need a way to know when the code is ready, even ifthe doc is missing.

Sometimes information is available if you know where to look for it (JIRAcomments & patches, javadocs, tests) or if slides are available from apresentation. Sometimes tinkering around works, or using the mailinglists.

Sure, that's not good enough for general users so pushing for wikidocsseems like a good idea. But let's not create a limbo of features and fixeswaiting for docs. Unless new doc resources are going to be allocated soon... ? <Shameless plug for getting more Hive tech writers.>

I like the release notes idea. When the doc is too elaborate for releasenotes, a link to the wikidoc could be given. If a design doc has currentinformation, that could be noted. If javadocs are sufficient, the classescould be listed.

A minor advantage of using a separate doc ticket is that it can be assignedto a writer or different developer without obscuring the codingresponsibility. And, of course, it boosts the JIRA count for contributorson the Credits <http://hive.apache.org/credits.html#Contributors> page(except that the link is broken).-- LeftyOn Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]> wrote:

> There is no guarantee that the subtask will ever get completed after> the feature goes in. There is no point of new features if users can't> actually figure how to use it.> I think we should either add sufficient documentation in the release> notes section of jira or add doc in wiki as upcoming feature before we> commit the changes.>>> On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <[EMAIL PROTECTED]>> wrote:> > I think opening a separate doc ticket and making it a subtask of the dev> > ticket works pretty well. The subtask can contain notes specific to> > documentation.> >> > Eugene> >> >> >> > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]> >wrote:> >> >> Hi,> >>> >> I wanted to ask how people feel about a policy where an issue is not> >> closed until documentation has been added to the Wiki?> >>> >> Problematic issues fall roughly in two categories:> >> * They have a generic title (add UDF for XY) an attached patch and a> >> few code reviews without ever even mentioning what the name or usage> >> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)> >>> >> * They have a design document or description with the intended syntax> >> but that's often not the final form so one has to look up the patch> >> (can't find a good example right now)> >>> >> Both are a lot of work to document for someone who has not followed> >> that issue. Tracking undocumented things would be got to not forget> >> about it and to have an incentive to do it.> >>> >> Obviously not all things need documentation, and not all things need> >> to be documented by the person who submitted the patch. But to make> >> things easier for documentation people it'd be great if the issue> >> could contain an up to date description of at least the syntax changes> >> and configuration options etc. so that we can tidy it up and transfer> >> it to the wiki. It's not nice to dig through patches for this.> >>> >> Another alternative would be to open issues like "Document HIVE-5252"> >> but I like the other option better.> >>> >> What do people think?> >>> >> Cheers,> >> Lars> >>> >> > --> > CONFIDENTIALITY NOTICE> > NOTICE: This message is intended for the use of the individual or entity> to> > which it is addressed and may contain information that is confidential,> > privileged and exempt from disclosure under applicable law. If the reader> > of this message is not the intended recipient, you are hereby notified> that> > any printing, copying, dissemination, distribution, disclosure or> > forwarding of this communication is strictly prohibited. If you have

Another advantage of separate doc ticket is that when we are making arelease it's easier to tell what has been checked in already and what elseneeds to be done and whether we should hold the release due to doc issuesor not. Release notes are only useful for people who already have a lot ofexperience with the product.

> Could a new status such as "Just needs doc" be added? Or perhaps a> resolution such as "Undocumented"? Because folks who want to get their> hands on new features need a way to know when the code is ready, even if> the doc is missing.>> Sometimes information is available if you know where to look for it (JIRA> comments & patches, javadocs, tests) or if slides are available from a> presentation. Sometimes tinkering around works, or using the mailing> lists.>> Sure, that's not good enough for general users so pushing for wikidocs> seems like a good idea. But let's not create a limbo of features and fixes> waiting for docs. Unless new doc resources are going to be allocated soon> ... ? <Shameless plug for getting more Hive tech writers.>>> I like the release notes idea. When the doc is too elaborate for release> notes, a link to the wikidoc could be given. If a design doc has current> information, that could be noted. If javadocs are sufficient, the classes> could be listed.>> A minor advantage of using a separate doc ticket is that it can be assigned> to a writer or different developer without obscuring the coding> responsibility. And, of course, it boosts the JIRA count for contributors> on the Credits <http://hive.apache.org/credits.html#Contributors> page> (except that the link is broken).>>> -- Lefty>>> On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]>> wrote:>> > There is no guarantee that the subtask will ever get completed after> > the feature goes in. There is no point of new features if users can't> > actually figure how to use it.> > I think we should either add sufficient documentation in the release> > notes section of jira or add doc in wiki as upcoming feature before we> > commit the changes.> >> >> > On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <[EMAIL PROTECTED]> >> > wrote:> > > I think opening a separate doc ticket and making it a subtask of the> dev> > > ticket works pretty well. The subtask can contain notes specific to> > > documentation.> > >> > > Eugene> > >> > >> > >> > > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]> > >wrote:> > >> > >> Hi,> > >>> > >> I wanted to ask how people feel about a policy where an issue is not> > >> closed until documentation has been added to the Wiki?> > >>> > >> Problematic issues fall roughly in two categories:> > >> * They have a generic title (add UDF for XY) an attached patch and a> > >> few code reviews without ever even mentioning what the name or usage> > >> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)> > >>> > >> * They have a design document or description with the intended syntax> > >> but that's often not the final form so one has to look up the patch> > >> (can't find a good example right now)> > >>> > >> Both are a lot of work to document for someone who has not followed> > >> that issue. Tracking undocumented things would be got to not forget> > >> about it and to have an incentive to do it.> > >>> > >> Obviously not all things need documentation, and not all things need> > >> to be documented by the person who submitted the patch. But to make> > >> things easier for documentation people it'd be great if the issue> > >> could contain an up to date description of at least the syntax changes> > >> and configuration options etc. so that we can tidy it up and transfer> > >> it to the wiki. It's not nice to dig through patches for this.> > >>> > >> Another alternative would be to open issues like "Document HIVE-5252"

CONFIDENTIALITY NOTICENOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.

I am fine with a followup doc jira if the enough information to createa document is there in the original jira (in form of release notessection of jira, or jira description etc). There has to be enoughinformation so that people who don't know hive internals can also dothe follow up work of updating the docs.

But I think committers need to ensure either the doc update is done aspart of committing process or a sufficient information is in the jiraand there is a follow up 'format the information and updateappropriate section in wiki' jira.On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz <[EMAIL PROTECTED]> wrote:> Could a new status such as "Just needs doc" be added? Or perhaps a> resolution such as "Undocumented"? Because folks who want to get their> hands on new features need a way to know when the code is ready, even if> the doc is missing.>> Sometimes information is available if you know where to look for it (JIRA> comments & patches, javadocs, tests) or if slides are available from a> presentation. Sometimes tinkering around works, or using the mailing> lists.>> Sure, that's not good enough for general users so pushing for wikidocs> seems like a good idea. But let's not create a limbo of features and fixes> waiting for docs. Unless new doc resources are going to be allocated soon> ... ? <Shameless plug for getting more Hive tech writers.>>> I like the release notes idea. When the doc is too elaborate for release> notes, a link to the wikidoc could be given. If a design doc has current> information, that could be noted. If javadocs are sufficient, the classes> could be listed.>> A minor advantage of using a separate doc ticket is that it can be assigned> to a writer or different developer without obscuring the coding> responsibility. And, of course, it boosts the JIRA count for contributors> on the Credits <http://hive.apache.org/credits.html#Contributors> page> (except that the link is broken).>>> -- Lefty>>> On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]> wrote:>>> There is no guarantee that the subtask will ever get completed after>> the feature goes in. There is no point of new features if users can't>> actually figure how to use it.>> I think we should either add sufficient documentation in the release>> notes section of jira or add doc in wiki as upcoming feature before we>> commit the changes.>>>>>> On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <[EMAIL PROTECTED]>>> wrote:>> > I think opening a separate doc ticket and making it a subtask of the dev>> > ticket works pretty well. The subtask can contain notes specific to>> > documentation.>> >>> > Eugene>> >>> >>> >>> > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]>> >wrote:>> >>> >> Hi,>> >>>> >> I wanted to ask how people feel about a policy where an issue is not>> >> closed until documentation has been added to the Wiki?>> >>>> >> Problematic issues fall roughly in two categories:>> >> * They have a generic title (add UDF for XY) an attached patch and a>> >> few code reviews without ever even mentioning what the name or usage>> >> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>)>> >>>> >> * They have a design document or description with the intended syntax>> >> but that's often not the final form so one has to look up the patch>> >> (can't find a good example right now)>> >>>> >> Both are a lot of work to document for someone who has not followed>> >> that issue. Tracking undocumented things would be got to not forget>> >> about it and to have an incentive to do it.>> >>>> >> Obviously not all things need documentation, and not all things need>> >> to be documented by the person who submitted the patch. But to make>> >> things easier for documentation people it'd be great if the issue>> >> could contain an up to date description of at least the syntax changes>> >> and configuration options etc. so that we can tidy it up and transfer

CONFIDENTIALITY NOTICENOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.

> I am fine with a followup doc jira if the enough information to create> a document is there in the original jira (in form of release notes> section of jira, or jira description etc). There has to be enough> information so that people who don't know hive internals can also do> the follow up work of updating the docs.>> But I think committers need to ensure either the doc update is done as> part of committing process or a sufficient information is in the jira> and there is a follow up 'format the information and update> appropriate section in wiki' jira.>>> On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz <[EMAIL PROTECTED]>> wrote:> > Could a new status such as "Just needs doc" be added? Or perhaps a> > resolution such as "Undocumented"? Because folks who want to get their> > hands on new features need a way to know when the code is ready, even if> > the doc is missing.> >> > Sometimes information is available if you know where to look for it (JIRA> > comments & patches, javadocs, tests) or if slides are available from a> > presentation. Sometimes tinkering around works, or using the mailing> > lists.> >> > Sure, that's not good enough for general users so pushing for wikidocs> > seems like a good idea. But let's not create a limbo of features and> fixes> > waiting for docs. Unless new doc resources are going to be allocated> soon> > ... ? <Shameless plug for getting more Hive tech writers.>> >> > I like the release notes idea. When the doc is too elaborate for release> > notes, a link to the wikidoc could be given. If a design doc has current> > information, that could be noted. If javadocs are sufficient, the> classes> > could be listed.> >> > A minor advantage of using a separate doc ticket is that it can be> assigned> > to a writer or different developer without obscuring the coding> > responsibility. And, of course, it boosts the JIRA count for> contributors> > on the Credits <http://hive.apache.org/credits.html#Contributors> page> > (except that the link is broken).> >> >> > -- Lefty> >> >> > On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]>> wrote:> >> >> There is no guarantee that the subtask will ever get completed after> >> the feature goes in. There is no point of new features if users can't> >> actually figure how to use it.> >> I think we should either add sufficient documentation in the release> >> notes section of jira or add doc in wiki as upcoming feature before we> >> commit the changes.> >>> >>> >> On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <> [EMAIL PROTECTED]>> >> wrote:> >> > I think opening a separate doc ticket and making it a subtask of the> dev> >> > ticket works pretty well. The subtask can contain notes specific to> >> > documentation.> >> >> >> > Eugene> >> >> >> >> >> >> >> > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]> >> >wrote:> >> >> >> >> Hi,> >> >>> >> >> I wanted to ask how people feel about a policy where an issue is not> >> >> closed until documentation has been added to the Wiki?> >> >>> >> >> Problematic issues fall roughly in two categories:> >> >> * They have a generic title (add UDF for XY) an attached patch and a> >> >> few code reviews without ever even mentioning what the name or usage> >> >> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252> >)> >> >>> >> >> * They have a design document or description with the intended syntax> >> >> but that's often not the final form so one has to look up the patch> >> >> (can't find a good example right now)> >> >>> >> >> Both are a lot of work to document for someone who has not followed> >> >> that issue. Tracking undocumented things would be got to not forget> >> >> about it and to have an incentive to do it.> >> >>> >> >> Obviously not all things need documentation, and not all things need

In case of pig, where the documentation is under same repository andversion controlled, the feature patch is expected to include thedocumentation changes as well, or at least documentation in releasenotes section that be used to create documentation.

On Wed, Nov 6, 2013 at 12:48 PM, Lefty Leverenz <[EMAIL PROTECTED]> wrote:> What do other projects do?>> -- Lefty>>> On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <[EMAIL PROTECTED]> wrote:>>> I am fine with a followup doc jira if the enough information to create>> a document is there in the original jira (in form of release notes>> section of jira, or jira description etc). There has to be enough>> information so that people who don't know hive internals can also do>> the follow up work of updating the docs.>>>> But I think committers need to ensure either the doc update is done as>> part of committing process or a sufficient information is in the jira>> and there is a follow up 'format the information and update>> appropriate section in wiki' jira.>>>>>> On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz <[EMAIL PROTECTED]>>> wrote:>> > Could a new status such as "Just needs doc" be added? Or perhaps a>> > resolution such as "Undocumented"? Because folks who want to get their>> > hands on new features need a way to know when the code is ready, even if>> > the doc is missing.>> >>> > Sometimes information is available if you know where to look for it (JIRA>> > comments & patches, javadocs, tests) or if slides are available from a>> > presentation. Sometimes tinkering around works, or using the mailing>> > lists.>> >>> > Sure, that's not good enough for general users so pushing for wikidocs>> > seems like a good idea. But let's not create a limbo of features and>> fixes>> > waiting for docs. Unless new doc resources are going to be allocated>> soon>> > ... ? <Shameless plug for getting more Hive tech writers.>>> >>> > I like the release notes idea. When the doc is too elaborate for release>> > notes, a link to the wikidoc could be given. If a design doc has current>> > information, that could be noted. If javadocs are sufficient, the>> classes>> > could be listed.>> >>> > A minor advantage of using a separate doc ticket is that it can be>> assigned>> > to a writer or different developer without obscuring the coding>> > responsibility. And, of course, it boosts the JIRA count for>> contributors>> > on the Credits <http://hive.apache.org/credits.html#Contributors> page>> > (except that the link is broken).>> >>> >>> > -- Lefty>> >>> >>> > On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]>>> wrote:>> >>> >> There is no guarantee that the subtask will ever get completed after>> >> the feature goes in. There is no point of new features if users can't>> >> actually figure how to use it.>> >> I think we should either add sufficient documentation in the release>> >> notes section of jira or add doc in wiki as upcoming feature before we>> >> commit the changes.>> >>>> >>>> >> On Tue, Nov 5, 2013 at 9:46 AM, Eugene Koifman <>> [EMAIL PROTECTED]>>> >> wrote:>> >> > I think opening a separate doc ticket and making it a subtask of the>> dev>> >> > ticket works pretty well. The subtask can contain notes specific to>> >> > documentation.>> >> >>> >> > Eugene>> >> >>> >> >>> >> >>> >> > On Tue, Nov 5, 2013 at 12:16 AM, Lars Francke <[EMAIL PROTECTED]>> >> >wrote:>> >> >>> >> >> Hi,>> >> >>>> >> >> I wanted to ask how people feel about a policy where an issue is not>> >> >> closed until documentation has been added to the Wiki?>> >> >>>> >> >> Problematic issues fall roughly in two categories:>> >> >> * They have a generic title (add UDF for XY) an attached patch and a>> >> >> few code reviews without ever even mentioning what the name or usage>> >> >> of the new UDF is (<https://issues.apache.org/jira/browse/HIVE-5252>> >)>> >> >>>> >> >> * They have a design document or description with the intended syntax

CONFIDENTIALITY NOTICENOTICE: This message is intended for the use of the individual or entity to which it is addressed and may contain information that is confidential, privileged and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient, you are hereby notified that any printing, copying, dissemination, distribution, disclosure or forwarding of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and delete it from your system. Thank You.

Well, if it works for Pig then let's give it a try for Hive. Unlesssomeone has a better idea, of course. (Nudge.) Both javadocs and wikidocsshould be strongly encouraged. Also hive-default.xml.template for newconfig parameters. Anything else?

By the way here's another example of a JIRA that hides its need fordocumentation: HIVE-4002<https://issues.apache.org/jira/browse/HIVE-4002>creates config param'hive.fetch.task.aggr' but doesn't mention it by nameanywhere except the patch, so when I did a JIRA search I couldn't find it.

I'm not trying to embarrass anyone, it's just that I try to keep track ofJIRAs that create user parameters or new syntax, and this one escapednotice until I was researching another hive.fetch.xxx.

> In case of pig, where the documentation is under same repository and> version controlled, the feature patch is expected to include the> documentation changes as well, or at least documentation in release> notes section that be used to create documentation.>>>> On Wed, Nov 6, 2013 at 12:48 PM, Lefty Leverenz <[EMAIL PROTECTED]>> wrote:> > What do other projects do?> >> > -- Lefty> >> >> > On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <[EMAIL PROTECTED]>> wrote:> >> >> I am fine with a followup doc jira if the enough information to create> >> a document is there in the original jira (in form of release notes> >> section of jira, or jira description etc). There has to be enough> >> information so that people who don't know hive internals can also do> >> the follow up work of updating the docs.> >>> >> But I think committers need to ensure either the doc update is done as> >> part of committing process or a sufficient information is in the jira> >> and there is a follow up 'format the information and update> >> appropriate section in wiki' jira.> >>> >>> >> On Wed, Nov 6, 2013 at 12:20 AM, Lefty Leverenz <> [EMAIL PROTECTED]>> >> wrote:> >> > Could a new status such as "Just needs doc" be added? Or perhaps a> >> > resolution such as "Undocumented"? Because folks who want to get> their> >> > hands on new features need a way to know when the code is ready, even> if> >> > the doc is missing.> >> >> >> > Sometimes information is available if you know where to look for it> (JIRA> >> > comments & patches, javadocs, tests) or if slides are available from a> >> > presentation. Sometimes tinkering around works, or using the mailing> >> > lists.> >> >> >> > Sure, that's not good enough for general users so pushing for wikidocs> >> > seems like a good idea. But let's not create a limbo of features and> >> fixes> >> > waiting for docs. Unless new doc resources are going to be allocated> >> soon> >> > ... ? <Shameless plug for getting more Hive tech writers.>> >> >> >> > I like the release notes idea. When the doc is too elaborate for> release> >> > notes, a link to the wikidoc could be given. If a design doc has> current> >> > information, that could be noted. If javadocs are sufficient, the> >> classes> >> > could be listed.> >> >> >> > A minor advantage of using a separate doc ticket is that it can be> >> assigned> >> > to a writer or different developer without obscuring the coding> >> > responsibility. And, of course, it boosts the JIRA count for> >> contributors> >> > on the Credits <http://hive.apache.org/credits.html#Contributors>> page> >> > (except that the link is broken).> >> >> >> >> >> > -- Lefty> >> >> >> >> >> > On Tue, Nov 5, 2013 at 2:40 PM, Thejas Nair <[EMAIL PROTECTED]>> >> wrote:> >> >> >> >> There is no guarantee that the subtask will ever get completed after> >> >> the feature goes in. There is no point of new features if users can't> >> >> actually figure how to use it.> >> >> I think we should either add sufficient documentation in the release> >> >> notes section of jira or add doc in wiki as upcoming feature before

In many cases, a release note can contain all the doc information or apointer to it. But sometimes it's more complicated. In any case, can weagree on a standard phrase such as TODO or DOC14 to put in the release noteso it's easy to find jiras that need user docs when the time comes?

Presumably the doc flag would be removed from the release note as soon asthe wiki has been updated. But realistically, some jiras wouldn't getdocumented in time for the release. So should those jiras get listedsomewhere at release time and have their doc flag removed, or do we wantthe world to see what's unfinished in the release notes?