Structure of Leo's User Documentation

[VR]

Hi Edward,

This morning I had a look at the documentation again and had the
thought,
that just by changing the structure a bit we could make it much easier
for
any user to read through the available information ...

I tried the following steps:

1) Move 'Chapter 9: History of Leo', 'Chapter 10: Theory of Operation'
and
'Chapter 11: White Papers' to the back of the document.
2) Move "Chapter 4: Leo’s Reference" to the back of the document.
3) Move 'Chapter 14: Creating Documents with Leo' forward in the
document
4) Move 'Chapter 20: Unit testing with Leo' before 'Chapter 16:
Debugging
with Leo'.
5) Move 'Chapter 15: Controlling Syntax Coloring' after 'Chapter 23:
Eliminating
sentinel lines with @shadow'.
6) Create a single "What's New in Leo" directory at the top-level and
put all
current "What's new in ..." directories below there.

Re-arranging the documentation along those lines would lead to the
following:

* Front Matter
* Preface
* What People Are Saying About Leo
* FAQ
* Slides
* Chapter 1: Installing Leo
* Chapter 2: The Leo Tutorial
* Chapter 3: Using Outlines
* Chapter 5: Using Leo’s Commands
* Chapter 6: Designing with Leo
* Chapter 14: Creating Documents with Leo
* Chapter 7: Scripting Leo with Python
* Chapter 8: Customizing Leo
* Chapter 12: Plugins
* Chapter 13: Writing Plugins
* Chapter 20: Unit testing with Leo
* Chapter 16: Debugging with Leo
* Chapter 17: Using ZODB with Leo
* Chapter 18: Leo and Emacs
* Chapter 19: Embedding Leo with the leoBridge module
* Chapter 21: IPython and Leo
* Chapter 22: Using Vim Bindings with Leo
* Chapter 23: Eliminating sentinel lines with @shadow
* Chapter 15: Controlling Syntax Coloring
* Chapter 4: Leo’s Reference
* Chapter 9: History of Leo
* Chapter 10: Theory of Operation
* Chapter 11: White Papers
* Appendices
* Glossary
* What’s New in Leo

What do you and others think ?

With kind regards,

Viktor

[Edward K. Ream]

On Sun, Sep 5, 2010 at 1:16 AM, VR <viktor....@gmail.com> wrote:

> This morning I had a look at the documentation again and had the thought, that just by changing the structure a bit we could make it much easier for any user to read through the available information ...

I like this idea. Indeed, we might consider going further and moving
some chapters into some kind of supplemental document.

The issue of Chapter numbers has always bothered me. There are just
barely useful. Any ideas how we could do without them?

Edward

[VR]

Hi Edward

On 5 Sep., 19:08, "Edward K. Ream" <edream...@gmail.com> wrote:

> On Sun, Sep 5, 2010 at 1:16 AM, VR <viktor.ransm...@gmail.com> wrote:
> > This morning I had a look at the documentation again and
> > had the thought, that just by changing the structure a bit
> > we could make it much easier for any user to read through
> > the available information ...
>
> I like this idea.  Indeed, we might consider going further and
> moving some chapters into some kind of supplemental document.

When I started thinking about it I wanted to propose the smallest
possible change to make the flow of reading easier. For whatever
reasons I was also under the impression that you wanted to keep
everything in one single document ...

Now that you mention the possibility of more than one document
I could think of at least two approaches:

Approach A: Distinguish clearly b/w 'Using Leo for whatever ...'
and 'Developing [for] Leo ...'

Approach B: Look at the Python documentation: Something
like ...

1) What's new
2) Tutorial
3) Reference
4) Setup
5) Extending & Embedding
6) FAQ

I'm sure others have more approaches to offer. - Let's discuss ...

> The issue of Chapter numbers has always bothered me.  There are just
> barely useful.  Any ideas how we could do without them?

I'm not sure I fully understand the intent of this question. - For me
it
would have been OK to rewrite the headlines of these nodes ...

Let me know if and how I could be of help with the documentation.

With kind regards,

Viktor

[Terry Brown]

On Sat, 4 Sep 2010 23:16:28 -0700 (PDT)
VR <viktor....@gmail.com> wrote:

> This morning I had a look at the documentation again and had the
> thought, that just by changing the structure a bit we could make
> it much easier for any user to read through the available information ...

At the risk of being repetitious, I've never found any documentation as accessible as Django's, from this starting point:

http://docs.djangoproject.com/en/dev/

OTOH, Django is "just" a web application and ORM system, where's Leo is, well, whatever you want :-)

Cheers -Terry

[Edward K. Ream]

On Sep 5, 2:51 pm, Terry Brown <terry_n_br...@yahoo.com> wrote:

> At the risk of being repetitious, I've never found any documentation as accessible as Django's, from this starting point:
>
>  http://docs.djangoproject.com/en/dev/

Ok. I've put this on the list of things to study.

EKR

[Edward K. Ream]

On Sep 5, 2:51 pm, Terry Brown <terry_n_br...@yahoo.com> wrote:

> At the risk of being repetitious, I've never found any documentation as accessible as Django's, from this starting point:

There are many good things about this documentation. It tells things
clearly, it has links to more detailed info, and the right nav pane is
much better than average: it includes a "you are here" tree and it
includes radio buttons to tailor searches.

I'll attempt to emulate as many of these features as possible.

EKR