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 <the...@hortonworks.com> 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 <ekoif...@hortonworks.com> > 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 <lars.fran...@gmail.com > >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 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. >
