[arc-discuss] Re: New/Updated ARC Policies and Best Practices

[Richard Lowe]

Gary Winiger wrote:
>> Why exactly would there be a need to 'dumb down' documentation for 
>> people on the outside?.
> 
> 	I don't think that was Ed's point.  I think he was looking for
> 	sufficient context in which to read the docs.  As I said, when
> 	I wrote most of this stuff, it was for people who alread understood.
> 	Perhaps unfortunately, most internal stuff in the past has
> 	been limited to internal only distribution -- at least until
> 	it was shipped.  That's changed and dragging the internal stuff
> 	out sometimes is more challenging because not all the context
> 	is easially available.   I think the two primary references
> 	are available and should be linked into to the opensolaris
> 	docs soon:

Well, I've done RBAC related stuff once, though for a change that I 
later decided shouldn't be made, so I'm aware that the documentation in 
question would have really helped me out (though yes, I've read other 
public documentation on the RBAC stuff, and various blogs mentioning it 
too).

I just feel the need to resist any kind of push to make the published 
documentation *user*-friendly, when users aren't at all the intended 
audience.  Technical documentation is what is useful, publishing 
background material in addition to it is certainly valuable 
(documentation from the various wikis one sees referenced, almost 
certainly).  But cutting up the internally available documentation to 
make it more palatable to an audience other than the one originally 
intended (and the one it's most useful to) can only end up losing 
information or context that may turn out to be valuable.

I'd even suggest that it'd be far better (in future, obviously) to use 
exactly the same documentation on both sides of fence, and given that, 
making edits to existing documentation seems fruitless (or likely to run 
the risk of all future documentation being similarly molested).


> http://developers.sun.com/solaris/articles/ais.html
> http://www.sun.com/software/whitepapers/wp-rbac/wp-rbac.pdf
> 

They already are linked from the pages referenced.

-- Rich