What do other projects do? -- Lefty
On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <the...@hortonworks.com> 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 <leftylever...@gmail.com> > 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 <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. > >> > > -- > 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. >
