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 20:48:25 GMT
What do other projects do?

-- Lefty


On Wed, Nov 6, 2013 at 3:07 PM, Thejas Nair <thejas@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 <leftyleverenz@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 <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.
> >>
>
> --
> 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