search

MarcWeber / vim-addon-manager

manage and install vim plugins (including their dependencies) in a sane way. If you have any trouble contact me. Usually I reply within 24 hours
Other
660 stars 59 forks source link

documentation is too complex. Its too hard to find the needle in the haystack #145

Closed MarcWeber closed 10 years ago

MarcWeber commented 10 years ago

https://github.com/gmarik/Vundle.vim/issues/241#issuecomment-34549179

ZyX-I commented 10 years ago

This shows that you should change your approach in documenting VAM. I remember this topic being raised before: you find or create something related to VAM and you immediately add this to documentation. That time I suggested to move most of this to github wiki.

Though current situation is better then before I joined (there was no documentation: only a few recipes with no structure), there are still issues. I would suggest to keep an absolute minimum in documentation and move everything else to wiki. The absolute minimum is

  1. Introduction. It should contain a usage example, but must not contain a huge piece of code that serves purpose of checking out VAM. Leave this to wiki, sample vimrc or whatever. It also should show what VAM actually does (i.e. checking out plugin source to a specific directory) and a few words about disabling and removing addons (a few == one phrase like “to remove a plugin remove its name from the list and then remove its directory from filesystem”, not a 11-line section like we have now).
  2. Definitions of API functions.
  3. Definitions of API commands.
  4. Options definitions.
  5. Definition of addon-info file.
  6. Possibly FAQ. Based on a common questions after documentation cleanup if they do not fit into other sections. This must be kept as short as possible.
  7. I would suggest a changelog here. Unfortunately, you do not release. Thus only contacts.

I also guess that auto_install should be 1 by default, not 0. I do not see why it should be there: to bother users? In “getting started” documentation I see two or more (depending on how you count three last places where auto_install is set to 1 in code blocks) places where it is suggested to set it to 1.

This is what should be contained in documentation. But how is a different thing. vundle.txt appears to be nice, but 90% of time when I was writing documentation I was simply copying documentation structure from the other projects so I cannot be considered an expert in this matter.

marlun commented 10 years ago

I had a look at VAM today too and I've done it before but just as @starcraftman noted in his response I find the docs and the README.md too large and complex so I always stop reading (stop caring).

The README.md should have as little as possible at the top to get the user going. A short intro and a config example with some popular plugins shown so people recognise it and know what to do.

I also have to agree with @ZyX-I after reading what @starcraftman wrote that auto-install should be default :)

On another note @MarcWeber your way of trying to get people to use your plugins and see your ideas is a little bit too obtrusive. I think it's great that you're trying to improve vim in places you believe it's less than what it should be but the way you're doing it now (at least it seems so to me) is by pushing for them pretty much everywhere, expanding the rules of where it's really appropriate. Keep the great work up writing good plugins and people will both find them and use them.

MarcWeber commented 10 years ago

You have to "obstrusive" to raise awareness and get feedback. Right now I feel that I've spent huge amounts of time for nothing - due to making some very small mistakes - documentation being too long and too complex - not because the software does not work. When I started VAM my intention was to improve code reusage - and at some point in time its time to check where you got for what reasons. If you read carefully my last message I also offered help to vundle, eg by improving vam.mawercer.de to support vundle, too. Also vim-pi effort should be considered. Maybe you don't know - but in the past it happened at least 10 times to me that people asked how to make snipmate work - and they all used the less featureful broken version of Sanders snipmate, because they found it by google on arbitrary sites. My goal was to lessen the probability to run into such "pain" (for all parts of the community) - because there are more important things to fix (but maybe I'm wrong about that, too)

marlun commented 10 years ago

On Sun, Feb 09, 2014 at 01:18:15AM -0800, Marc Weber wrote:

You have to "obstrusive" to raise awareness and get feedback.

You don't. I understand that you have to work to get your ideas heard but you have to think hard about when it's appropriate to push for your plugins and when it's not. People asking about snipmate is a great example of when you should do it.

Right now I feel that I've spent huge amounts of time for nothing - due to making some very small mistakes - documentation being too long and too complex - not because the software does not work. When I started VAM my intention was to improve code reusage - and at some point in time its time to check where you got for what reasons.

It would be bad to see documentation problems as small mistakes. If you want people to use your plugins documentation is an important issue. I'm no expert but for example I don't think tlib and matchit is very good examples to use because it's not two plugins that people know what they do. Having exmaples like CtrlP, NERDTree or some Tim Pope plugin would be better because it's what a lot of users use.

If you read carefully my last message I also offered help to vundle, eg by improving vam.mawercer.de to support vundle, too. Also vim-pi effort should be considered. Maybe you don't know - but in the past it happened at least 10 times to me that people asked how to make snipmate work - and they all used the less featureful broken version of Sanders snipmate, because they found it by google on arbitrary sites. My goal was to lessen the probability to run into such "pain" (for all parts of the community) - because there are more important things to fix (but maybe I'm wrong about that, too)

It's important not to annoy people too because then they'll start to ignore the plugins not because they are bad but because they are tiered of hearing about them where they want to discuss other things. It would for example be better to just start a new vundle issue talking about vim-pi compared to posting in an issue where the author of vundle asked about getting help.

Martin Lundberg

steveno commented 10 years ago

I just spent the past 30 minute converting to VAM from Vundle. I really think that's too much. It doesn't need to be that hard. I don't see why there can't be a very short and simple, "here's how you set it up" in the README. The version that is in there doesn't work. It just spits errors at you constantly; thus my 30 minute installation time. I think if you could fix this one issue that would be a massive boon for you to gain converts.

@MarcWeber you haven't wasted your time man. You've just got competition; and it sucks. I think you have a superior product here; you just need to polish it for the masses. A diamond in the rough if you will.

As an example, here are the steps I ended up taking to get VAM working properly.

1) Add the following to the top of your vimrc

" put this line first in ~/.vimrc
set nocompatible | filetype indent plugin on | syn on

fun SetupVAM()
  let c = get(g:, 'vim_addon_manager', {})
  let g:vim_addon_manager = c
  let c.plugin_root_dir = expand('$HOME', 1) . '/.vim/vim-addons'
  let &rtp.=(empty(&rtp)?'':',').c.plugin_root_dir.'/vim-addon-manager'
  if !isdirectory(c.plugin_root_dir.'/vim-addon-manager/autoload')
    execute '!git clone --depth=1 git://github.com/MarcWeber/vim-addon-manager '
                \       shellescape(c.plugin_root_dir.'/vim-addon-manager', 1)
  endif
  call vam#ActivateAddons([], {'auto_install' : 0})
endfun
call SetupVAM()

2) Close and reopen Vim. It will ask you to install vim-addon-manager. Say "Yes". 3) Remove everything you added in step 1. 3) Now add the following

set nocompatible | filetype indent plugin on | syn on

set rtp+=~/.vim/vim-addons/vim-addon-manager
call vam#ActivateAddons(['github:SirVer/ultisnips'], {'auto_install' : 0})
call vam#ActivateAddons(['github:honza/vim-snippets'], {'auto_install' : 0})

4) Feel free to add or remove as many plugins as you wish. For further documentation on the syntax, how install from other VSCs, or use to manage local plugins see the getting started page or the additional docs.

MarcWeber commented 10 years ago

Have a look at the new README. The git clone command is only executed if VAM is not on your disk yet. Thus its meant to be kept there so that copying your .vimrc is enough to bootstrap. If you think differently keep your minimal version. I also decided that just VAMActivate is nicer than call vam#ActivateAddons([], {opts}). Vundle is right about this. Its also ZyX's work. Kudos to him, too. The last truly missing option is parallel installation or a progress display - both would be quite some work. I don't see the value in it. For speed reasons vam#ActivateAddons should be called only once - but probably the difference is too small to worry about.

MarcWeber commented 10 years ago

The README is fine now, closing this issue