From: Eric Armstrong <Eric.Armstrong@...>
Date: 2006-05-16T07:56:11+09:00
Subject: Re: Ruby & Emacs

First, thanks to John for pointing out that FreeRide
is most likely exactly the thing I'm using for.

Next, Pistos:

After many years coding, I became a writer. But I
still code whenever I can. But the result of the
writing experience led me to start writing the user
guide as part of the design process.

    Note for aqile developers:
    The user guide is one of process artifacts at
    every stage. You modify it at the start of each
    cycle to explain what you plan to have accomplished
    at the end of the cycle. If the plan changes, you
    modify the document accordingly.

That experience had several tremendous benefits:

   * When I finally finished coding a project, I was
     generally too burned out to write a user guide.

   * Since a project was never really "finished", it
     was hard to define that point at which I really
     /should/ write the guide.

   * When I was coding, a myriad of ideas would occur
     to me about things the users ought to know. When
     I wrote at the end of a project, I always had the
     nagging feeling that I was only recalling a fraction
     of the things I wanted to say.

   * But with the user guide already written, it's an
     easy matter to add such things as they come in
     note format to be fleshed out later, if in no other
     form.

I've used that strategy successfully on several projects.
The user guide lets people give me feedback on how they
want to work even before it's written. And you never
find yourself in that awful position where you've created
something great, but no one uses it because they can't
find out how.

I'll do a design document as well, to keep track of 
implementation ideas. Between the two of them, I've
never needed a "specification".


Pistos Christou wrote:
> John Gabriele wrote:
>> I just had a brief look at Diakonos. Seems nice and clean: just one
>> main .rb file for the editor, and one conf file. Sadly, aside from a
>> few comments here and there in the code and in the conf file, Diakonos
>> looks to be entirely undocumented.
>>
>> There *is* a readme describing how to install (which is (happily)
>> trivial), but no mention anywhere how to use the editor (though,
>> passing "--help" (I guessed that one) gives 4 lines of info). I also
>> guessed that Ctrl-q exits the editor, but that's it.
> 
> You are absolutely correct: There is very little user documentation.  I 
> actually have more solid plans to come up with more material (online 
> documentation, in-application help) to give a better out-of-box 
> experience within the next two releases.  I've walked a few people 
> through getting started, but I completely agree that a quick start 
> walkthrough of some kind is definitely in order.  That and sprucing up 
> the F1 page by, perhaps, organizing into groups and showing the most 
> commonly used keybindings higher up.
> 
> I've also entertained notions of making a "for people coming from emacs" 
> conf file which would override most keystrokes to match emacs.
> 
> Thanks for trying Diakonos.
> 
> Pistos
>