hive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lefty Leverenz <leftylever...@gmail.com>
Subject Re: Documentation Policy
Date Wed, 06 Nov 2013 08:20:59 GMT
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 <thejas@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 <ekoifman@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.francke@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.
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message