[implementations-list] How important is a Vimpulse user manual? How to make one? Copy from Vim docs?

Sat Dec 26 01:55:36 CET 2009

> From: jasonspiro3 at gmail.com
> Date: Wed, 23 Dec 2009 22:54:20 -0500
>
> Vimpulse needs better documentation -- a better user manual, saying
> how to use all of its features. Look at the Viper info manual and see
> how great it is. Look at our documentation -- it's very incomplete.

My view is that while Viper's manual is wonderfully comprehensive and
wonderful in its comprehensiveness, it is not a good role model for
Vimpulse. Vimpulse should be as no-nonsense as emacsly possible
-- you load it up and start typing -- and along those lines, its
documentation should be small, concise and straight to the point. This
is just my view, of course, but I've googled a dozen accounts of how a
Vim user would try the Emacs/Viper route, stumble onto some annoying
inconsistency, and eventually give up on Emacs altogether. I therefore
see as one of Vimpulse's main challenges to hold on to a new user for
sufficiently long that they get "hooked" and maybe start exploring
what amazingly cool things you can do when the underlying substrate
consists of Emacs Lisp.

Vim is a programmer's editor, in the true sense of that term. This is
most apparent when looking up the documentation. The help files of a
"popular" Windows editor like Notepad++ is full of friendly
screenshots and easy-to-follow explanations of how you can perform a
search and replace on your text in just six simple steps, but makes no
mention at all of remapping the internals or tweaking cryptic
variables. Vim's documentation has no pictures, but its level of
detail is staggering, as seen when issuing ":help <BS>":

        [count] characters to the left.  |exclusive| motion.
        Note: If you prefer <BS> to delete a character, use
        the mapping:
                :map CTRL-V<BS>         X
        (to enter "CTRL-V<BS>" type the CTRL-V key, followed
        by the <BS> key)
        See |:fixdel| if the <BS> key does not do what you
        want.

This is as no-nonsense as you can get. It is also overwhelmingly
newbie-unfriendly. If you were to make a Vimpulse's User's Manual out
of it, you wouldn't tell a Vim user anything they didn't know, nor a
newbie anything they'd want to hear.

What is it a Vim user doesn't know, then? Emacs, and Emacs Lisp. How
to (setq ...) variables rather than :set them, how to tweak whatever
needs tweaking, how to combine the power of Vim with the power of
Emacs. All of this should be shown by example. When you've never used
Lisp before, it is okay to copy and modify an expression without
understanding completely how it works.

But it mustn't be too overwhelming. At least not at first sight. Load
it, tweak it, use it; the whole thing should be as transparent and
straightforward as possible. To that end, maybe Vimpulse should load
and configure Viper automatically, so that a single
(require 'vimpulse) is sufficient to get started.

I'm reminded of how Unix gained massive popularity not because it was
consistent and complete, but because it was portable and practical.
Vimpulse should at least be practical. Its documentation should be
clear, example-loaded and straight to the point, and preferably some
measures shorter than this e-mail, if possible.

My two cents. :)

_________________________________________________________________
Få nye Windows Live™ Messenger.
http://download.live.com/messenger