-
Notifications
You must be signed in to change notification settings - Fork 59
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
documentation is too complex. Its too hard to find the needle in the haystack #145
Comments
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
I also guess that This is what should be contained in documentation. But how is a different thing. |
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. |
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) |
On Sun, Feb 09, 2014 at 01:18:15AM -0800, Marc Weber wrote:
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.
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.
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 |
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.
" 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()
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})
|
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. |
The README is fine now, closing this issue |
VundleVim/Vundle.vim#241 (comment)
The text was updated successfully, but these errors were encountered: