Don't be such a (computer) scientist

[Edward K. Ream]

I ran across a review of "Don't be such a scientist":

http://www.amazon.com/Dont-Be-Such-Scientist-Substance/dp/1597265632

It's good timing because I'll be revising Leo's docs in the following
weeks, preparing for a talk.

As most of us know, Leo's docs need lots of work.

Edward

[Edward K. Ream]

On Nov 3, 10:06 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> As most of us know, Leo's docs need lots of work.

I haven't read the book yet, but even the reviews have been helpful.
Here is yet another intro to Leo. It focuses less on the technical
details, and more on "arousal".

QQQ
Leo is an outliner on a mission:

To be the ultimate power tool for managing complex data
like books, databases and computer programs.

Leo grew out of my frustration in understanding complex computer
programs. Leo
has developed into a superb programming environment. Leo has also
developed into
a data management environment that blends the best features of
relational,
hierarchical and object oriented databases.

Anyone can use Leo, but Leo is designed for power users. Some of the
best programmers
in the world use Leo, and continue to contribute to its development.

Features

Like any outliner, newbies can use Leo like a filing cabinet to
organize text,
pictures or other data.

But Leo's outlines are no ordinary outlines:

1. You can organize Leo outlines in as many was as you like: You don't
have to
choose a single "right" way to view your data. You are *not*
limited to a
hierarchical or relational view of data. You can create a new view
of your
data at any time.

2. You can connect external files to Leo's outlines. Saving a Leo
outline can
change one or more external files. Conversely, changing an exteral
file can
update a Leo outline.

As a result, a single Leo outline naturally represents complex
projects that
span many files, for example, computer programs, databases and
books.

3. Leo's outlines are fully scriptable with Python. The interaction
between
outlines and Leo scripts is really what makes Leo unique:

- Any node in a Leo outline can contain a Leo script. You can
execute this
script at any time.

- You can **build** scripts and external files from parts of an
outline.
This allows you to organize your source code as an outline:
outline
structure can be an essential part of your code.

- Scripts can *easily* access or change any part of a Leo outline.
In other
words, Leo has a full, complete DOM (Document object model).

- Any Leo script can be applied to any outline node. "Bringing
scripts to
data" is simple, fun and powerful.

- You can customize any part of Leo using scripts and plugins.
Many of Leo's
features started life this way.

- Leo's headlines naturally describe the data in each node.
Scripts and
plugins can use these descriptions (metadata) to find data
without having
to parse the actual data.

These features are easy to use, yet Leo's community of users has been
exploring
their implications for over 10 years. New ways to combine outline
structure with
scripting continue to be invented.
QQQ

On a web page, the details of point 3 would likely be a separate page,
or even a separate chapter.

Feel free to comment, or improve.

Edward

[Ville M. Vainio]

On Tue, Nov 3, 2009 at 6:06 PM, Edward K. Ream <edre...@gmail.com> wrote:

> As most of us know, Leo's docs need lots of work.

I think the time our wave accounts activate, we can experiment with
moving the documentation process to wave. I don't know how well that
will work with rst, but I'm sure it can be *made* to work.

After we get our accounts, we should have enough invitations to go
around for anyone willing to contribute.

--
Ville M. Vainio
http://tinyurl.com/vainio

[Edward K. Ream]

On Wed, Nov 4, 2009 at 3:41 AM, Ville M. Vainio <viva...@gmail.com> wrote:

On Tue, Nov 3, 2009 at 6:06 PM, Edward K. Ream <edre...@gmail.com> wrote:

> As most of us know, Leo's docs need lots of work.

I think the time our wave accounts activate, we can experiment with
moving the documentation process to wave. I don't know how well that
will work with rst, but I'm sure it can be *made* to work.

I was thinking the same thing.

After we get our accounts, we should have enough invitations to go
around for anyone willing to contribute.

I didn't know that :-)

Edward

[Edward K. Ream]

On Nov 3, 12:38 pm, "Edward K. Ream" <edream...@gmail.com> wrote:
> On Nov 3, 10:06 am, "Edward K. Ream" <edream...@gmail.com> wrote:
>
> > As most of us know, Leo's docs need lots of work.
>
> I haven't read the book yet, but even the reviews have been helpful.
> Here is yet another intro to Leo.  It focuses less on the technical
> details, and more on "arousal".

Here is another draft. I'm not sure it is any better in terms of
"Don't be such a scientist", which I haven't read yet, but I'm kinda
happy with it. Imo, it gives some sense to the newbie of how Leo
might offer something new, without going into a lot of details.
Anyway, it is a baseline for further work:

Leo is an outliner on a mission:

To be the ultimate power tool for managing complex data

like computer programs, books and databases.

Leo started life as a way to understand complex computer programs.
Later, it became a data management environment that blends the best

features of relational, hierarchical and object oriented databases.

Newbies can use Leo outlines like a filing cabinet to organize text,
pictures and other data. But Leo is designed for power users. Some
of the world's best programmers use Leo. Leo has a large community of
sophisticated users who continue to improve Leo.

Leo gives you three inter-related and complementary power tools:

1. Leo's outlines are graphs, not simple hierarchies.
2. You can extend any part of Leo using the Python language.
3. Leo's outline structure is significant everywhere.

The first power tool: Leo outlines are graphs

Leo outlines are not simple hierarchies, they are DAG's (Directed
Acyclic Graphs). This means that you can organize Leo outlines in as
many was as you like. You don't have to choose a single "right" way to
view your data. You are *not*limited to a hierarchical or relational

view of data. You can create a new view of your data at any time.

These views are normal parts of a Leo outline, not something tacked
onto the outline.

The second power tool: you can extend any part of Leo with Python

Leo is completely and easily extensible. Scripting and extending Leo
is a large subject, but you should understand the following right from
the start:

- Leo is written in 100% pure Python, and all aspects of Leo are
scriptable in Python.

- Leo outlines contain **nodes** consisting of headlines and body
text. Outlines and nodes are true Python objects.

- Any node in Leo can contain a **Leo script**. Leo scripts have full
access to all nodes in a Leo outline. In other words, Leo has a DOM
(Document Object Model). Leo scripts also have access to all of Leo's
source code.

- Leo scripts can easily create **script buttons** that appear in
Leo's window. When you press one of those buttons Leo executes the
script on the presently selected node. The catch-phrase for this is
"bringing scripts to data", and it has unlimited uses.

- You can customize any aspect of Leo's operation with scripts, script
buttons or plugins. Many of Leo's core features started out this way.

The third power tool: outline structure is significant everywhere.

In Leo, outline structure matters. It's not something tacked on as an
afterthought. This is another large topic, but you should understand
the following right from the start:

- Parts of Leo outlines can correspond to external files on your file
system. Saving a Leo outline updates the corresponding external
files. Conversely, changing an external file will update the Leo
outline the next time you load the outline. Thus, a single Leo outline
can naturally represent a complex projects comprising many files.

- Leo uses outline structure in non-trivial ways (we'll discuss the
rules later) when writing external files or creating scripts. This
means that outlines structure becomes an integral part of external
files and scripts. Leo creates a new dimension for programming.
Programs are no longer merely classes and data, they also have
inherent outline structure.

- Most of Leo's commands understand outline structure. They can work
on all of the outline, or selected parts. Some examples:

A. Leo's file command can search all of the outline or just selected
parts. Because Leo outlines can contain many external files, Leo's
find command can work like a normal find, or like grep.

B. Leo's run-unit-test command command executes Python code in the
body of an @test node (a node with @test in the headline) as a unit
test, **without** having to set up the typical unit testing classes.
Writing the run-unit-test command was straightforward: the command has
easy access to body text without having to do any difficult parsing.

C. Continuing the @test example, you can run a single unit test by
selecting a single node; you can run a suite of unit tests by
selecting a larger part of the outline. This makes running exactly
the unit tests you want a snap. The kind of usage pattern happens
everywhere.

- Headlines naturally describe the body text of a node. By
convention, headlines that start with @x denote a node of type x.
@test is one such type; there are many others: @rst (contains
reStructuredText), @url (Leo opens the url in a browser when the node
is double-clicked), @button (creates script buttons), @command
(creates user-defined commands). Scripts and plugins can easily
create other user-defined types.

Summary

Leo's features create a unique environment for programming and for
managing data. They are easy to use, yet Leo's community of users has

been exploring their implications for over 10 years.

QQQ

Edward

[Edward K. Ream]

On Nov 4, 9:48 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> Here is another draft.  I'm not sure it is any better in terms of
> "Don't be such a scientist", which I haven't read yet, but I'm kinda
> happy with it.  Imo, it gives some sense to the newbie of how Leo
> might offer something new, without going into a lot of details.

It's interesting trying to guess what "Don't be such a scientist" is
going to say.

It does seem that the less technical an intro, the more compelling it
is.

As I reread old docs, I am struck by how useless many details there
are :-)

Joyce Carol Oates has said that her great strength is in revision,
which I take to mean a re-visioning of original material. I've only
begun to re-imagine Leo's introduction.

The "less details, the better" idea is suggestive, as is the phrase,
"don't be so unfriendly". A more friendly intro might discuss how
various kinds of people might use Leo. This reminds me that I've
forgotten to mention the ipython plugin :-)

Edward

[jkn]

> On Nov 4, 9:48 am, "Edward K. Ream" <edream...@gmail.com> wrote:
>
> > Here is another draft.

> > [...]

In terms of arousal - which I agree is a good way of approaching it,
and one unfamiliar, nay scary, to many of a technical bent - it's good
to remember to *make it personal*. Use the *You* word...


[suggestion]

Leo aims to be your ultimate power tool, allowing you to manage a wide
variety of
complex data forms. Computer programs, books and databases are all
examples of
domains where Leo can make your life easier.

Leo started life as a way to help users understand complex computer
programs. It has grown from there to
become what we call a 'data management environment'. One way of
thinking about this is that it blends the best

features of relational, hierarchical and object oriented databases.

...

[/suggestion]

J^n

[Edward K. Ream]

On Wed, Nov 4, 2009 at 4:31 PM, jkn <jkn...@nicorp.f9.co.uk> wrote:

> On Nov 4, 9:48 am, "Edward K. Ream" <edream...@gmail.com> wrote:
>
> > Here is another draft.

> > [...]

In terms of arousal - which I agree is a good way of approaching it,
and one unfamiliar, nay scary, to many of a technical bent - it's good
to remember to *make it personal*. Use the *You*  word...

That may be part of it.  The best example of friendly writing about Leo is my brother's intro:

http://webpages.charter.net/edreamleo/SpeedReam.html

To me, this is chatty, warm and somehow friendly, though I can't put my finger on exactly why.  To write this way more often would be a big step forward for me.

Edward

[Kent Tenney]

Here's style tips on writing for a technical journal, might be useful.
http://www.linuxjournal.com/xstatic/author/authguide

They stress active voice, see section starting
"Passive Voice Should Never Be Used by You"

[Edward K. Ream]

On Wed, Nov 4, 2009 at 7:35 PM, Kent Tenney <kte...@gmail.com> wrote:

Here's style tips on writing for a technical journal, might be useful.
http://www.linuxjournal.com/xstatic/author/authguide

They stress active voice, see section starting
"Passive Voice Should Never Be Used by You"

Thanks for this comment.

True, active voice is much stronger than passive voice, but the distinction "friendly" is different, imo.

I spend a lot of time converting passive constructions to active constructions.  The key, in my mind, is that the subject must be explicit.  *Leo* does something, or *I* do something, or *you* do something, or even *some technical construct* does something. Of course, the "doing something" is a stand-in for a verb, and as a first approximation the zippier the verbs the better.

I just checked my second draft, and I don't see even a single passive construction.  Do you?  There are also lots of "you"'s in the draft.  And I would say that the tone of the draft is compatible with the style guideline, "Write as though you were chatting with an intelligent friend who may not be familiar with the specifics of what you are covering."

And yet, I would rate the friendliness of the second draft as substantially less than my brother's description of Leo.  So there is something more to be learned :-)

Edward

P.S.  After waiting days for my local bookstore to fail to deliver the book, I just ordered it from Amazon and it should arrive Friday.  So we have until then to wonder what its admonitions mean :-)  Wonder is good, so the delay will make any Aha's more memorable.

EKR

[Edward K. Ream]

On Nov 4, 8:01 pm, "Edward K. Ream" <edream...@gmail.com> wrote:

> And yet, I would rate the friendliness of the second draft as substantially
> less than my brother's description of Leo.  So there is something more to be
> learned :-)

I spent several hours today on a new slide show for Leo. Forgetting
about friendliness for a moment, the thing that keeps hitting me right
between the eyes is how useless the techie details are in conveying
what Leo is all about. This is actually a big opening for
improvement. It greatly expands what might be effective beyond the
blah blah blah of syntax, definitions of terms etc.

I actually think the latest draft is a substantial improvement in this
regard. Tantalizingly, it may turn out to be just the beginning of a
re-imagining of what would be a compelling message about Leo.

EKR

[Gour]

On Wed, 4 Nov 2009 18:14:08 -0800 (PST)
>>>>>> "Edward" == "Edward K. Ream" >>>>>> wrote:

Edward> I spent several hours today on a new slide show for Leo.

Great!

Edward> Forgetting about friendliness for a moment, the thing that
Edward> keeps hitting me right between the eyes is how useless the
Edward> techie details are in conveying what Leo is all about.

I went through all the docs yesterday (just skipped over few chapters
like debugging etc.) as well as through all the tutorials/slide-shows,
so let me just add my 0.02HRK (Croatian kunas)...

Edward> I actually think the latest draft is a substantial improvement
Edward> in this regard. Tantalizingly, it may turn out to be just the
Edward> beginning of a re-imagining of what would be a compelling
Edward> message about Leo.

I'm not sure if this is the intention, but the docs gives impression
that Leo is (mostly) meant to do Python-related stuff with it
(something which was/is problem with e.g. Pida's doc).

otoh, I'd say that there should be more stuff like: "These
capabilities, all by themselves, would make Leo an excellent choice for
editing rST documents." making Leo extremely useful for people who
(besides writing - Haskell - programs with Leo) would use it for e.g.
writing study notes and/or assignment papers via RST plugin giving them
opportunity to get good-enough (pdf) output with docutils/sphinx...

Sincerely,
Gour

--

Gour | Hlapicina, Croatia | GPG key: F96FF5F6
----------------------------------------------------------------

[Edward K. Ream]

On Wed, Nov 4, 2009 at 11:51 PM, Gour <go...@gour-nitai.com> wrote:

I'm not sure if this is the intention, but the docs gives impression
that Leo is (mostly) meant to do Python-related stuff with it
(something which was/is problem with e.g. Pida's doc).

otoh, I'd say that there should be more stuff like: "These
capabilities, all by themselves, would make Leo an excellent choice for
editing rST documents." making Leo extremely useful for people who
(besides writing - Haskell - programs with Leo) would use it for e.g.
writing study notes and/or assignment papers via RST plugin giving them
opportunity to get good-enough (pdf) output with docutils/sphinx...

Thanks for this.  It's hard to see this kind of blind spot, especially when editing existing docs.

And I like the little story in the dependent clause :-)

At present, the "conclusions" section is weak, and this kind of language might find a home there, or in other places.

Edward

[Geoff Evans]

This is progress! The proposed introduction has, for the first time,
made
me think I might want to put the time into learning scripts. I've had
a go
at modifying the second draft slightly with two thoughts in mind.
First
the description is still largely a "tool view" and it might be useful
to have
a complementary "problem view" to show prospective users that Leo
will do for them things they want done. Secondly I found it still a
bit
heavy on the technical jargon. At this stage you simply want to show
that it can be handy; the fact that it's also clever will emerge
naturally
as people start to play with it. I'm not the first person to suggest
that
quickstart.leo be integrated more with the documentation, and I've
suggested a template for how this might be done.

If you think any of this is going in a useful direction, I can try
more
along similar lines.

Side note to Edward and Ville: I did finally convert from xubuntu to
ubuntu. Put my computer totally out of commission for half a week
but got there in the end. Turns out the problem of the outline pane
going black is a combination of blackbox and the qt gui: with gnome
and qt or with blackbox and tk everything is fine. So my default is
the latter: I *like* my desktop to start off with a blank slate.

Best, geoff

=================================================

Leo is an outliner on a mission:

    To be the ultimate power tool for managing complex data

    like computer programs, books and databases: useful from
the start; hard to outgrow.

Leo started life as a way to understand complex computer programs.
Later, it became a data management environment that blends the best
features of relational, hierarchical and object oriented databases.

A Leo outline can simply be like a filing cabinet to organize text,
pictures and other data.   But it can be much more, because of three

inter-related and complementary power tools:

1. Leo's outline structure is flexible.

2. You can extend any part of Leo using the Python language.
3. Leo's outline structure is significant everywhere.

The first power tool: Leo's outline structure is flexible

You can organize Leo outlines in as many was as you like. You don't

have
to choose a single "right" way to view your data. You are *not*limited
to a hierarchical or relational view of data. You can create a new
view
of your data at any time. These views are normal parts of a Leo
outline,
not something tacked onto the outline.

The second power tool: you can extend any part of Leo with Python

Leo is completely and easily extensible.  Scripting and extending Leo
is a large subject, but you should understand the following right from
the start:

- Leo is written in 100% pure Python; in other words, when you are
editing a Leo outline, Python is doing all the work "down in the
engine
room". Why would you want to know that? Because Leo also allows
you
to build a trapdoor into your outline, through which you can reach
down into the engine room, do anything Python is capable of doing,
and bring the results back to your outline.

- More precisely, any node in Leo can contain a **Leo script**.  Leo
scripts have full access to all nodes in a Leo outline.  So suppose
for
example you have ... and you would like to do .... You
can write a Leo script to do precisely that. [Once you have Leo
installed and running, the supplied outline 'quickstart.leo' shows
you how in the node Grandparent-->Parent-->Child.]

- Leo outlines contain **nodes** consisting of headlines and body
text.  Outlines and nodes are true Python objects.

[Edward K. Ream]

On Thu, Nov 5, 2009 at 10:42 AM, Geoff Evans <gtev...@nl.rogers.com> wrote:

This is progress!  The proposed introduction has, for the first time, made me think I might want to put the time into learning scripts.  I've had a go at modifying the second draft slightly with two thoughts in mind.

I like this process.  Several of your changes remove needless nerdy terminology.

I'm not convinced with this, though:

QQQ

  Leo is written in 100% pure Python; in other words, when you are editing a Leo
  outline, Python is doing all the work "down in the engine room". Why would you
  want to know that? Because Leo also allows you to build a trapdoor into your
  outline, through which you can reach down into the engine room, do anything
  Python is capable of doing, and bring the results back to your outline.

QQQ

I like the story-telling here, but the "engine room" analogy is a bit too cute, imo.

I do wish we had a wave to play with this.

How about something like this?

  Leo is written in 100% pure Python.  Why would you want to know that?  Because
  Leo allows you to write Python scripts that allow you to do anything Python is
  capable of doing.  These scripts can get information from your outline, and put
  their results back into the outline.

Edward

[Edward K. Ream]

On Thu, Nov 5, 2009 at 11:21 AM, Edward K. Ream <edre...@gmail.com> wrote:

How about something like this?

  Leo is written in 100% pure Python.  Why would you want to know that?  Because
  Leo allows you to write Python scripts that allow you to do anything Python is
  capable of doing.  These scripts can get information from your outline, and put
  their results back into the outline.

Oops.  Two "allows" in one sentence:

  Leo is written in 100% pure Python.  Why would you want to know that?  Because

  you can write Leo scripts that can do anything Python can do.  In particular, Leo's
  Python scripts can get information from your outline, and put their results back into the outline.

EKR

[Edward K. Ream]

On Nov 5, 11:24 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> > How about something like this?

QQQ

Leo is written in 100% pure Python.  Why would you want to know that?
Because Leo allows you to write Python scripts that allow you to do
anything Python is capable of doing.  These scripts can get
information from your outline, and put their results back into the
outline.

QQQ

> Oops.  Two "allows" in one sentence:

QQQ

Leo is written in 100% pure Python.  Why would you want to know that?
Because you can write Leo scripts that can do anything Python can do.
 In
particular, Leo's Python scripts can get information from your
outline, and put their results back into the outline.

QQQ

No. This is subtly going in the wrong direction. The pithier the
summary, the less story telling is happening.

Let's try to be a bit more "chatty":

Leo is written in 100% pure Python. Why would you want to know that?

Because you can write Python scripts in any Leo node, and these
scripts
can do anything that Python can do, and they do it **to the data in
the Leo outline.** That is, Leo scripts can can get information from

your outline, and put their results back into the outline.

Still not great, perhaps, but a bit better.

The problem with writing is that you have to tell stories in some
reasonable order. In Geoff's version, the next paragraph was:

- More precisely, any node in Leo can contain a **Leo script**. Leo
scripts have full access to all nodes in a Leo outline. So suppose

for example you have ... and you would like to do ....You can write a

Leo script to do precisely that.

The temptation is to try to define "Leo script" first, to make the
previous version a bit more precise, but then the definition slows
down the exposition. And so it goes.

Edward

[Edward K. Ream]

On Nov 5, 11:47 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> The temptation is to try to define "Leo script" first, to make the
> previous version a bit more precise, but then the definition slows
> down the exposition.  And so it goes.

As I was driving along, the solution hit me: make definitions into
stories. Doh! Why didn't I think of that before?

Instead of dryly defining a Leo script, we could say something like
this:

We call a Python script that appears in Leo's body pane a **Leo
script** to emphasize that the script has full access to all aspects
of Leo, including all the data in your outline and all of the classes,
methods and data in Leo's own source code. For example, suppose...

Edward

[jkn]

On Nov 5, 1:25 am, "Edward K. Ream" <edream...@gmail.com> wrote:
>
> That may be part of it.  The best example of friendly writing about Leo is
> my brother's intro:
>
> http://webpages.charter.net/edreamleo/SpeedReam.html
>
> To me, this is chatty, warm and somehow friendly, though I can't put my
> finger on exactly why.  To write this way more often would be a big step
> forward for me.

It reads almost as though Speed is talking to a friend, over a coffee,
or something. So do the same....

Imagine talking about Leo to a non-technical friend - they're
interested, but don't want or need to know much about what goes on
under the hood. What would you say? What questions would they ask? How
ywouldyou get them *excited*?

You might try actually sitting down and doing this - actually talk to
someone instead of typing. Record yourself, with a little MP3 recorder
or something. I know I have to force myself not to revert to tech-
style when I'm at a keyboard. Your unedited speaking sentences may
well be better than your typed ones for this purpose. It's a bit of a
cringe getting over how your voice sounds at first, but that soon
goes. Listen back and transcribe the bits that you like. It's a useful
thing to do in many ways.

J^n

[Edward K. Ream]

On Thu, Nov 5, 2009 at 4:38 PM, jkn <jkn...@nicorp.f9.co.uk> wrote:

On Nov 5, 1:25 am, "Edward K. Ream" <edream...@gmail.com> wrote:
>
> That may be part of it.  The best example of friendly writing about Leo is
> my brother's intro:
>
> http://webpages.charter.net/edreamleo/SpeedReam.html
>
> To me, this is chatty, warm and somehow friendly, though I can't put my
> finger on exactly why.  To write this way more often would be a big step
> forward for me.

It reads almost as though Speed is talking to a friend, over a coffee,
or something. So do the same....

Imagine talking about Leo to a non-technical friend - they're
interested, but don't want or need to know much about what goes on
under the hood. What would you say? What questions would they ask? How
ywouldyou get them *excited*?

Thanks for this suggestion.

Ironically, after working for several days on the words for a Leo slideshow to be given at a talk, my son James, who knows about presentations, suggests that most slides should have very little words.  This forces the listener to actually listen to what I am saying.  In other words, the visual channel tends to overwhelm the audio channel, and the only apparent solution is to dim the visual channel.

This is going to be a bit of trick, because the slideshow is going to use Leo, and it will *show* many of Leo's features, rather than just talk about them.  Still, I think this approach is going to work.  Indeed, the visuals will all be "real Leo", rather than attempts to summarize Leo.  It could be the crucial difference.

As many of you may know, I am a firm believer that the more that can be thrown away, the better the final product will be.  I've certainly thrown away a *lot* of words about Leo lately :-)  This effort has not been wasted.

Indeed, the "elevator talk" about Leo has been distilled to a very short summary:

    Leo is about *vision* and *power*.  Leo's flexible outlines give a new way of seeing data.
    Leo's Python scripts, acting on Leo's outlines, bring a new kind of power to programming.
    You can do things in Leo that you can not even *think about* in emacs or vim.

So I think I am getting close to a pretty effective talk.  James says that slides are only a backdrop: what matters is practicing the presentation.

The Leo slideshow will be an interesting experiment, because there still will be plenty of visuals, but they will be visuals of Leo in action.  As an aid to my talk, I've created "real" Leo nodes that help the talk.  For example, I'll refer to nodes in leoPy.leo to show actual views of an outline.

To do this, I'll use @url nodes so I don't have to fumble around:  I'll just execute the double-click-icon-box command to jump directly to the node.  This has potential.  I can use one @url node to jump to an @rst node to show rst sources, then use another @url node to show the corresponding page on the web. There are other ways to use "helper" nodes to illustrate what Leo can do.  I plan to show @test, @html, @button, and (maybe) @rst.

But the important point is that nobody is going to look at my laboriously-created-yet-fundamentally-uninteresting words *about* Leo.  They will be looking at the real deal.

To make this work, I will indeed have to practice the talk.  I want to distill my 15 years of work with Leo into about 15 minute talk.  The elevator talk about distills the 15 years into about 15 seconds :-)

Edward

P.S.  I want a very short Leo talk for two, no three, reasons.  First, I want to leave room for a second talk about how to manage an open-source project.  Second, I want to leave time for interactions.  Third, everybody likes a talk shorter than expected :-)

EKR

[Geoff Evans]

I agree the engine room was a bad idea; in fact I was ready to
discard it even before reading Edward's reaction. I've been thinking
since that it might help to split the second power tool into two:

=============================

2. You have easy access to a powerful programming language.
3. You can easily automate operations on your outline.

2: Leo is written in Python: when you are editing a Leo
outline your are -- from a different perspective -- running
scripts in a Python session. More than that, Leo makes it easy
for you to write your own Python script in a node of your outline,
and execute it when you want. Or, by opening a Leo session and
and an IPython session, you can ....

3: The components and organization of your outline are Python
objects, and you can write Python scripts to see them and act on
them. (Let us define a "Leo script" as a Python script that acts
on the Leo outline it is a component of.) It is hard to grasp the
power of this at first; but suppose, for example, you have ...
and you want to ...

==============================

Reasons for the split: There really are two ideas here and I found
it easy to get confused when documentation talked sometimes of Leo
scripts and sometimes of Python scripts. The first idea has more
applications: if my own learning experience is typical, one will want
to start by using Leo to help do the work one really wants to do, and
only later worry about making it an even more powerful tool.

Another thought: I know it's not Leo, but if someone could put into
quickstart.leo (is there a pointer to this file on Leo's home page?)
what I have to do to turn a restructured text file into LaTex, with
a trivial example, it would flatten my learning curve a lot.

geoff

[Edward K. Ream]

On Sun, Nov 8, 2009 at 7:17 AM, Geoff Evans <gtev...@nl.rogers.com> wrote:

2:   Leo is written in Python: when you are editing a Leo
outline your are -- from a different perspective -- running
scripts in a Python session.  More than that, Leo makes it easy
for you to write your own Python script in a node of your outline,
and execute it when you want.  Or, by opening a Leo session and
and an IPython session, you can .... 

3:   The components and organization of your outline are Python
objects, and you can write Python scripts to see them and act on
them.  (Let us define a "Leo script" as a Python script that acts
on the Leo outline it is a component of.)  It is hard to grasp the
power of this at first; but suppose, for example, you have ...
and you want to ...

I like these words.  They tell a nice story.

I'm moving away from the "mission" and "power tool" structure.  I don't think they are nearly strong enough.  But we'll probably find a way to use these stories somewhere.

The essence of the "vision" and "power" organization is correct, but I'm not comfortable with either word because neither is concrete.  And they are nouns, not verbs.  But the overall organization is, I think correct.  There are two, and *only* two key elements of Leo:

1.  Leo is a new way of seeing data, including programs.

2.  Leo is a new way of applying scripts to data.

These are, at least, based on verbs.

These two points are, really and truly, what make Leo unique.  For point 1, the key idea/story is that there is *no* single right way of organizing data.  It's not just that the user must be given the opportunity to organize that data as she sees fit, it is that *she* doesn't know what organization will be right until a task comes along that needs doing.  Then she'll know what organization is right for her *for that task*, but she won't want to abandon all her previous organizations.  She wants to organize her data in many ways, and she wants to be able to keep all over her organizations indefinitely.

This is a pretty good story, imo.  Note that stories mostly eliminate the need to try to get the "perfect" words.  In that sense, stories are much easier to write than typical marketing slogans.  And they are much more powerful.  And they don't sound like they were written by a hack.

BTW, I am about finished with "Don't be Such a Scientist".  It's an excellent book, and I highly recommend it, but it really is focused on communicating science, not just communication in general.  OTOH, it is written as nothing but interesting stories, and the author does, in fact, realize that stories are the heart of the matter.  "Arouse and fulfill" is mostly a sideshow, and not a very convincing sideshow at that.  But if you care about the anti-science movement, as I do, you will find this book to have a wealth of important information.  Did you know that when creationists and evolutionary biologists debate, the creationists almost always win? This book will tell you why.  And now I'm not so upset about it.  In fact, I find it hilarious. You may too, at the appropriate spot in the book.

Ok.  On to point 2.   The story here is that Leo makes it trivial to apply scripts to outlines, to use outlines to organize scripts and external files.  Moreover, the user, that is, the script writer, can use headlines to assign script-specific types to the data in the body text.  In the past, scripts (including Leo's core) have used the @x convention to assign type "x" to body text, but that's only a convention.  Scripts could also use uA's, for instance, to assign types to data.  The story here is actually quite a bit more complex, because there are so many non-obvious applications.  @test, @rst, @html and @button are examples,  and each is a unique application of the general idea that Leo is a breakthrough in applying scripts to data.  OTOH, the fact that the story is fairly long simply means that it can be interesting, and should be.

I plan to discuss point 2 only in a haiku-like way in my slideshow.  There simply isn't time to do more than give glimpses of possibilities.  But in the introduction there is time to expand the story.

To repeat what I think is the most important aha.  Stories are easier to tell because the can be much more relaxed.  They don't depend on impossible-to-achieve-perfect-words.  Instead, they depend on lots and lots of verbs, woven together in what really can be quite a meandering way.  The example from Mannahatta is a great example.  It's vivid and compelling, but I bet the author didn't agonize over the words.  Similarly, in this posting I'm not "working" at the words.  I'm really telling a story.  It's *so* much easier.

Edward

[jkn]

Hi Edward

[..]

> There are two, and *only* two key elements of Leo:
>
> 1.  Leo is a new way of seeing data, including programs.
>
> 2.  Leo is a new way of applying scripts to data.
>

FWIW I think this a better kind of 'elevator script' than the 'vision
and power' stuff.

J^n

[Edward K. Ream]

Right.  Vision and power are feeble nouns, no matter how popular they may be among the marketing class.

Edward

[Matt Wilkie]

To the elevator pitch (and they lend themselves to demonstration): For
me the pivotal reasons to try Leo were/are:

* Ability to edit external text files, in place, with others not using
Leo, invisibly.

* Comments adjacent to externals, that move with externals, yet (can
be) invisible to the externals.

* Organize any way you like, in many trees, without copying.

It's always interesting to me how some themes arise closely in time in
apparently disconnected venues. This conversation is in line with
something else I've just read, "Figuring out what your company is all
about" (http://joelonsoftware.com/items/2009/11/01.html). "...if you
can’t explain your mission in the form, “We help $TYPE_OF_PERSON be
awesome at $THING,” you are not going to have passionate users."

cheers,

-matt

[Matt Wilkie]

> * Organize any way you like, in many trees, without copying.

...and without sacrificing original structure.

--
-matt