search

Shougo / dein.vim

:zap: Dark powered Vim/Neovim plugin manager
MIT License
3.42k stars 197 forks source link

Suggestion to improve documentation #471

Closed ghost closed 1 year ago

ghost commented 1 year ago

Hi, hope y'all are doing great!

I suggest the creation of a markdown-styled doc/wiki of the project.

Current documentation

Currently, we have the doc/dein.txt file containing everything. However, the file is growing to more than 1k lines with a diversity of information, which for most advanced users isn't a problem, but for the new users is not the best choice.

Suggestion

A good approach would be creating a Github Wiki page, allowing the community to work at it, and organizing the information by sections with more examples and use cases.

Then later we can start working to decrease the size of the doc/dein.txt file, leaving only the most required information.

What do y'all think about it?

Help links

4513ECHO commented 1 year ago

I think it should not be. GitHub Wiki cannnot be seen from Vim.

ghost commented 1 year ago

I think it should not be. GitHub Wiki cannnot be seen from Vim.

Remember, we are not complete removing doc/dein.txt, and we can still view Github Wiki from vim by cloning the repo with .wiki.git at the end.

Creating the Github Wiki is for the users who want access an markdown-styled documentation on Github, which currently there's none, only an cody text file.

Shougo commented 1 year ago

I don't want to decrease current documentation. It is not my policy. But you can create wiki pages for new users.

https://github.com/Shougo/dein.vim/wiki

ghost commented 1 year ago

Hey @Shougo

Please, create a public repo named dein.vim-wiki

This way the community can open PR and discuss the Github Wiki changes in one place.

From dein.vim-wiki you would push the necessary files to https://github.com/Shougo/dein.vim.wiki.git after confirming that everything is okay.

Note: The Shougo/dein.vim-wiki repo would only deal with changes relative to the docs on Github Wiki, no binary or vim/lua files.

It make things clear and organized. It's a way to avoid extra issues or PR on the main repo.

Shougo commented 1 year ago

Please, create a public repo named dein.vim-wiki

Why the public repository is needed? Please provide the information for it.

You can clone the wiki repository.

I have tested to create dein.vim-wiki, but it is failed. the name seems reserved.

ghost commented 1 year ago

Why the public repository is needed? Please provide the information for it.

The main reason is to avoid issues and pull requests that are only related to documentation to be open on this repo.

Without an separated repo the following could occur:

The issues and PR related only to Github Wiki could cause annoyance for those whatching the project.

I have tested to create dein.vim-wiki, but it is failed. the name seems reserved.

Strange, maybe you already create one? If not you could try a different name like dein-vim-wiki or dein-vim-docs?

If you don't want it, the alternative could be something like this Merge Wiki Changes From A Forked Github Repo?

Shougo commented 1 year ago

If not you could try a different name like dein-vim-wiki or dein-vim-docs?

I don't want to create another repository for it.

Without an separated repo the following could occur:

It may be. But I think it is not really big problem.

ghost commented 1 year ago

Alright. I'll write the new Wiki on my forked repo and when It's finished I'll open another issue here.

By the way, there's a lot to write & format, and with my limited 20-40min time every day, I'll take some time to finish this. Feel free to discuss anything about my new changes to Dein.vim Wiki here