search

nvim-neorg / neorg

Modernity meets insane extensibility. The future of organizing your life in Neovim.
GNU General Public License v3.0
6.31k stars 209 forks source link

What is this? #677

Closed simsrw73 closed 1 year ago

simsrw73 commented 1 year ago

Issues

Feature description

I've spent about 10-15 mins browsing readme & wiki, etc. and I have no idea what this is. It mentions emacs so maybe this is only something useful to emacs users? I saw this plugin mentioned somewhere in a discussion on taking notes and wanted to know what it's about, but I can't find any information that explains anything beyond installing & configuring.

What is this? What does it do? Why should I use it? Is it only for people in the know? Is there anything for non-emacs users to read to figure out what this does and how to use it?

Sorry, being silly and exaggerating a good bit, but serious question.

Help

No

Implementation help

No response

max397574 commented 1 year ago

short answer: it's a neovim plugin for the norg markup format with some extra tools and utilities

simsrw73 commented 1 year ago

I could have written that better. Not trying to be a jerk. Just trying to make the point that new users who've never heard org mode will look at your docs and see nothing to make them want to use it or investigate further. It would be ideal if the first thing visible tells what it is and how it's useful without referring to some other app or some dry specification document.

arsham commented 1 year ago

I could have written that better. Not trying to be a jerk...

That is not nice, you could have written this better.

Many of us that landed here and use this plugin got the gist of it by looking at the nice gifs in the README.md file. There is also a help section if you would like to read them in neovim. I personally joined the discord channel and had a few conversation with nice developers, and they have been a saint.

As I understand this plugin has not reached the GA phase yet, and it gets some backward incompatible changes from time-to-time. In the discussions you can find some chats about how to present this plugin better. But for now they are in process of making the API stable.

vhyrro commented 1 year ago

Hi!

Explaining what this plugin truly does is a bit... fuzzy right now, mostly because all of the features that this plugin will do and will be designed to do are not implemented, so I can't really say "this plugin is for xyz" just yet :p

I'll try explain the best I can though: Neorg is, very generically put, an organizational tool. And while this is incredibly vague, that's kind of the point, as Neorg is for everything related to organization. This includes notes, task and project management, writing typeset documents like theses, zettelkasten, scientific notes with latex support, slideshows and so on. The premise is that all of these features are centered around a single base file format that you only have to learn once and can use for all of the features. This single file format can also be exported to ideally anything, including word documents, man pages, presentations, latex, html etc. (this would be handled by pandoc).

It's compared much to org mode because it gives people in the know a quick and easy reference point of what to expect, but will obviously confuse newcomers. I totally don't want it to stay this way, but because of the awkwardness of trying to explain a product that doesn't do everything it will do one day it can't really be easily explained. I can't just call it "a markdown alternative" because that's not what it is, it's much more than that. Do you kind of see why the whole readme is a bit awkwardly worded? It's trying to explain something that it can't because the features aren't there, but it can't be explained in a simplified way because then the whole point of the project loses meaning.

On a positive note, things have been going in the right direction - the syntax is very very close to a 1.0 release, which'll be the first stable release. After we have a baseline - a source of truth - we'll be able to more accurately convey what it is this project does :p. I'll also be releasing a set of tutorials on youtube aimed at explaining how to use Neorg and what it's for.

Hope that answers your question! Ask away if something's unclear :)

simsrw73 commented 1 year ago

Hope that answers your question!

Thank you. That makes sense. I'll bookmark and check back when it's closer to release ready to learn more. It looks interesting. Appreciate the work you're doing.

danymat commented 1 year ago

Closing it as it seems cleared! Thanks everyone