against documentation by JIRA

[Michael Bieniosek <mi...@powerset.com>]

Hi,

I've noticed that, often, when someone asks about a new feature in hadoop,
they are referred to the relevant JIRA.

On several occasions I have tried to read JIRAs to figure out how a new
feature is supposed to work, and I almost always find myself more confused
than when I started.   The problem is that JIRA issues are essentially
discussions or arguments about how an issue should be designed and
implemented.  But as a user, I don't really care about the rejected designs,
failed tests, discussions about coding style, etc.  For example,
HADOOP-1298, the issue for dfs file permissions, spans 9 months and contains
over 200k of text.  I just want to know how I can use dfs permissions.

So, I ask hadoop developers, please document your features on the website,
not just on the JIRA!

Thanks,
Michael

Re: against documentation by JIRA

[Raghu Angadi <ra...@yahoo-inc.com>]

A user guide for permissions is already written. Not sure why it does 
not show up on hadoop main site. For now, you can view at 
http://svn.apache.org/viewvc/hadoop/core/trunk/docs/hdfs_permissions_guide.pdf

I doubt anyone here thinks Jira is a substitute for proper 
documentation. Like good software, good documentation is hard, probably 
much harder.

It might have been used when the alternative is zero documentation, 
Though some Jira's have some html/pdf/MSDOC attached to them

Raghu.

Michael Bieniosek wrote:
> Hi,
> 
> I've noticed that, often, when someone asks about a new feature in hadoop,
> they are referred to the relevant JIRA.
> 
> On several occasions I have tried to read JIRAs to figure out how a new
> feature is supposed to work, and I almost always find myself more confused
> than when I started.   The problem is that JIRA issues are essentially
> discussions or arguments about how an issue should be designed and
> implemented.  But as a user, I don't really care about the rejected designs,
> failed tests, discussions about coding style, etc.  For example,
> HADOOP-1298, the issue for dfs file permissions, spans 9 months and contains
> over 200k of text.  I just want to know how I can use dfs permissions.
> 
> So, I ask hadoop developers, please document your features on the website,
> not just on the JIRA!
> 
> Thanks,
> Michael
>