[Sugar-devel] Future of Rainbow + Sugar?

[Carol Farlow Lerche]

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:



> Thanks you for this detailed critique of my documentation efforts to date.
> One
> thing that I've (obviously) struggled with is understanding which audiences
> require which sorts of documentation. Your continued assistance untangling
> this
> mess is most appreciated.
>

I would be happy to supply detailed editorial comments to any effort you
make to provide a unified Rainbow document.

  ... write
> a tutorial about it that would make it more apparent how much is actually
> implemented and what an activity can do with it.
>

I'll see what I can cook up.


You might consider:

Specifically list aspects of program operation that are forbidden or limited
in the application, by default, under the current implementation.

Tell why the restriction is there, from a user-benefit perspective.

If these restrictions can be overcome by configuration files or programmatic
calls, list these under the restriction description.

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?)

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."

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.


> Do you have an example of documentation which you think really nailed the
> divide between "what is needed", "what exists", "how good is it?", and "how
> do
> I use it?"
>

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.


>
> As it happens, the main feature which exists is primitive filesystem
> isolation.
>

Well, I'd stick to documenting that, and save the blue sky for an appendix.

For me, these questions are largely answered by the statements, scattered
> throughout the system, that rainbow operates by inventing new uids for
> programs
> which it is asked to isolate. However, I can certainly lay things out more
> explicitly. Thank you for the reminder about active vs. passive voice.
>

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.

What are the concerns of activity developers?
>
> To date, the only one which I have heard clearly articulated is:
>
>  "How do I turn rainbow off for testing?"


> which, in fact, is answered in the "For Activity Developers" section
>

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sugarlabs.org/archive/sugar-devel/attachments/20090224/1b6f668b/attachment.htm