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
