Michael, I'm happy to continue this discussion off-list if you or others feel it is inappropriate to carry it on here.  However, to respond to your mail:<br><br><div class="gmail_quote"><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
Thanks you for this detailed critique of my documentation efforts to date. One<br>
thing that I've (obviously) struggled with is understanding which audiences<br>
require which sorts of documentation. Your continued assistance untangling this<br>
mess is most appreciated.<div class="Ih2E3d"></div></blockquote><div class="Ih2E3d"><br>I would be happy to supply detailed editorial comments to any effort you make to provide a unified Rainbow document. <br><br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> 
... write<br>
a tutorial about it that would make it more apparent how much is actually<br>
implemented and what an activity can do with it.<br>
</blockquote>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
I'll see what I can cook up.</blockquote><div><br>You might consider:  <br><br>Specifically list aspects of program operation that are forbidden or limited in the application, by default, under the current implementation.<br>
<br>Tell why the restriction is there, from a user-benefit perspective.<br><br>If these restrictions can be overcome by configuration files or programmatic calls, list these under the restriction description.<br><br>Point out explicitly where a developer would see evidence of the restriction being called into play (which log, e.g., and where is it?  Do you need to turn on logging in some way to see the messages?)<br>
<br>You might want to create a separate tutorial from the standpoint of other desktop environment developers, along the lines of "what to do to implement Rainbow in your environment."<br><br>I already here voices chiming in that all anyone needs is to read the code.  But could those chiming voices please recognize that there is a difference between the effort people will go to in conforming to or using a feature that they don't entirely belive in, (rather than just turning it off) compared to being provided easy access and understanding.<br>
 </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Do you have an example of documentation which you think really nailed the<br>
divide between "what is needed", "what exists", "how good is it?", and "how do<br>
I use it?"<div class="Ih2E3d"><br>
</div></blockquote><div><br>It is uncommon to document future features unless they are realistically expected to be implemented soon, except perhaps as an appendix of unresolved issues, or "bugs" sections as in man pages.  But frequently documentation addresses features that are only present in later versions.  Often this is set off by color, inline images of some kind or similar visual cues.<br>
 </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
As it happens, the main feature which exists is primitive filesystem isolation.<div class="Ih2E3d"></div></blockquote><div><br>Well, I'd stick to documenting that, and save the blue sky for an appendix.<br><br></div>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">For me, these questions are largely answered by the statements, scattered<br>
throughout the system, that rainbow operates by inventing new uids for programs<br>
which it is asked to isolate. However, I can certainly lay things out more<br>
explicitly. Thank you for the reminder about active vs. passive voice.<div class="Ih2E3d"></div></blockquote><div><br>Persons with a deep or even a moderate interest in security would understand that that was the case, but we're talking about a hoped-for community of activity developers including educators and learners that have so far proved unable to cross a rather high barrier of entry.<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">What are the concerns of activity developers?<br>
<br>
To date, the only one which I have heard clearly articulated is:<br>
<br>
  "How do I turn rainbow off for testing?" </blockquote><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><br>
which, in fact, is answered in the "For Activity Developers" section<br></blockquote></div><br clear="all">In this case, perhaps we should contemplate why someone would want to turn off rainbow, rather than using information that tells them what Rainbow is preventing.  Can I offer the analogy of the dreaded Windows security problems in which applications written for early versions of Windows silently broke when MS introduced new access violation error returns that the programs were unaware of?  These errors could often be eliminated by end users through granting constrained privileges to various Windows resources, but instead most people just did the simple thing.  They ran the application as administrator (analogous to turning Rainbow off).  All the bad consequences followed.  Btw I don't think it was just that developers turned off Rainbow.  Users did too, because activities had been written outside the context of Rainbow, then it was turned on.<br>