I revamped the README of zetteldesk.el to make it easier to understand. What do you think of it?

Last week, I released my new emacs package [zetteldesk.el](https://github.com/Vidianos-Giannitsis/zetteldesk.el) and made a [post](https://www.reddit.com/r/emacs/comments/t2prfo/new_package_zetteldeskel_a_tool_for_revision_and/) here for showcasing it. The idea was rather well accepted but I got a lot of feedback, that the README was too dense in information and it was hard for a new user to try it. I have tried fixing this, by integrating gifs for demonstrations instead of the raw info (which I moved to the wiki for anyone wanting it), adding a set of default bindings in the form of a hydra and a small sample config to get you started. ​ I believe some people might have been set off by those problems, so I wanted to say thank you for pointing them out. I would love to hear what you think of it now, that I have tried to make it more explanative and if it is truly easier for someone to get started with it. ​ As I said in the other post, I am very new to this, so I really appreciate and listen to feedback, as I feel the idea itself is good, but some parts of the implementation may be lacking, and who better to help me than the community. ​ Thank you all for helping, Best regards, Vidianos

What would be fantastic is a one paragraph summary, just before installation instructions. For me, I have scanned your README a few times over the last two weeks are so and get mentally lost. I love parenthetical, margin notes, footnotes and so forth, but struggle with gleaning the "Why would I want to use this?" And I think there's something in this repository for me to consider. >Welcome to zetteldesk.el, a small library I wrote on top of Org-Roam. Now you may ask, why this was written and what purpose does it fulfill. Well, I am not sure, there are quite a lot of reasons I wanted to do this, I can’t say I wrote it for one in specific. But there were two main ideas. The first being that I wanted some way to filter down my zettelkasten while doing revision for uni exams. That's half of a paragraph to say: "I wanted a way to filter down my zettlekasten while doing revisions for uni exams". Yet I can see a joy in your writing as you lead up to that sentence. > The second is a quote I read from “How to Take Smart Notes” that sparked an interest in my mind, and when I finally got the time to look into it, I made this. I want to see the quote; that quote appears to be a key driver into the work you did. Call attention to it, help others who've read that book see the launch point. Consider the quote as an epigraph for this section…of for the entire readme. And as I got to the "Getting Started Section" > With that out of the way, lets do a short introduction to some core features of the package. This only scratches the surface of what this package can do however. Its just a demonstration of some of the major features, with gifs in between for a better visual representation. For more detailed documentation check the Wiki, or the doc-strings of the functions. For some reason, if you are viewing this in Firefox, the gifs will be very grainy as mentioned in this issue. This is unfixed as of now as I am unaware of what is causing this. For now, I recommend viewing this in a Chromium browser which renders it better, but if you have any clue of how I could fix this feel free to mention it in the issue and I will fix it as soon as possible. This is a lot of text that says little about "Getting Started". As the author, I'm looking to you to help me understand the "why would I want to use this package" and I struggle to scan for relevant information.

After looking over the readme for about a minute I don't really have any idea what the package does. IMO the best READMEs: 1. Start with a compelling and clear "elevator pitch", with an image or video if applicable 2. Then include simple "Getting started" instructions, covering installation and maybe a basic "Hello world" use-case. (Asides about how you personally don't use straight, for example, are not relevant to most users) 3. Then, if you use a README-as-documentation approach, goes into detailed docs 4. Then lastly goes into debugging and contribution info. The general idea is to order the info according to how many users will want to know it. Debugging info is hopefully not necessary for most users, so it should go at the end! I'd also generally recommend distilling the text down quite a lot, as a "wall of text" will turn away most readers.

Ok, so basically you are saying it needs better ordering and a shorter summary to help you understand what this achieves. I will keep this in mind and try implementing it. I just personally despise READMEs which are very brief and only introduce the idea without any use case for it or a tutorial of what the core functions do, so I just made the polar opposite. I know it might be too long, and I could improve on that, but I am trying to avoid making it too brief. However its a good point. Many people have short attention spans, especially for something they don't know if they will like so I can make a section where I briefly introduce the concept in a single paragraph to make people understand what this is and if it is interesting to them, they can read on. Thanks for the tips

[deleted]

>What would be fantastic is a one paragraph summary, just before installation instructions Yeah, that's a good point, will look into that. >I want to see the quote; that quote appears to be a key driver into the work you did This is another good point, I initially avoided that as it truly is gonna take a while to find it. I know its somewhere in the book, but I have completely forgotten where. I guess I can try briefly going through pages until I find it. Will do my best I guess as it might be able to help others. ​ >This is a lot of text that says little about "Getting Started". You are definitely correct, but I felt the need to mention those things. In general, I guess I can try reordering some stuff and writing others more brief. I was just trying to avoid making a very brief README that only introduces the idea and then mentions no use case or how you are supposed to use the core functions. I really like in-depth documentation as I find it very time consuming to have to figure out everything (or most things) on my own. That's all. Will keep your recommendations in mind and try to make a very brief introduction in the start and keep the in-depth part for anyone that's interested in that.

>having > 30 MB of gifs is a bit too much for my taste and I would have found it more helpful if you ran the commands via M-x and not the keybindings (cloning is rather slow) Yeah, that was worrying me as well, how can I make them smaller. Should I drop the quality and if so to what. I was worried they wouldn't look good so I exported to 1080p. >I do not get what info-buffers are and how they work Info is the built-in help menu for emacs, where you read documentation (invoked through C-h i). I use it a lot so I added ways to handle info nodes inside zetteldesk. >Other than that, I think that the differentiation between zetteldesk-buffers and zetteldesk-scratch is a bit cumbersome. I would find it more intuitive to always act on a specific zetteldesk-buffer. zetteldesk-buffers are all the buffers that belong to the zetteldesk (e.g. you have explicitly selected to add them). zetteldesk-scratch is the unique buffer created for inserting the contents of files. A lot of commands act on that buffer as I wanted a clean buffer that I could insert the things there. But I guess if the difference isn't fully apparent, I will add an explanation somewhere. Thanks for your time in checking it out again!

It is much better, the gifs ,hydras, installation options, Mention of alternative packages (although I don't know if I missed this last one in the previous version due to the density of the text). Personally, I think the first paragraph should mention specifically what the package is for, which is still not clear. Look at the description of Delve: "It provides tools to collect, inspect and edit Org Roam Nodes in a separate application buffer. It helps you to quickly establish and maintain a project-specific subset of Org Roam Nodes"

Yeah all of these are new features I considered worth adding. About the summary, it totally slipped my mind. Its been mentioned in other comments and thinking of it, it was something I wanted to add. But it seems I completely forgot about it today. But I am glad I got the rest correct

[deleted]

The author really needs to add that one-paragraph description to posts like this. This is the first time I’ve heard of this package, and I have no clue what it is.

They are just suggestions! there is no correct or wrong.

Just want to say I was put off by the massive wall of text before, but this is so much better! As others have said, before the installation I would put a very small introduction saying what it is very plainly. Like this [https://github.com/minad/vertico](https://github.com/minad/vertico), very important for people skimming through repos. Excited to explore this more!

Thanks, will be adding one, but for some reason it completely slipped off my mind today. It was something I meant to do.

>IMHO the GIFs do not add a lot of value. One GIF quickly illustrating the idea might be enough for me Ok, I might reconsider the structure of it. But I think its better than the previous iteration at least. >I think you should make it clearer, that info nodes refer to the Emacs manual. Furthermore, I would suggest to keep this functionality separate, since it is not a core feature of org-roam That's definitely not a bad idea. I was considering this, actually. The reason I didn't split it is because the Info program is built-in to Emacs so it didn't add unnecessary dependencies. But yeah, its definitely not a core feature so I could split it up. >What do you think about creating a defcustom variable which specifies whether to insert contents in the current buffer (if it is a zetteldesk-buffer) or insert into a scratch buffer? Hadn't thought of something like this. Will take some work, but it should be possible with an if expression inside the code. But to make sure we are on the same page, you want the insertion functions to act on the current buffer instead of the scratch buffer right?

This comment cracked me up. Zettlekasten is specifically designed for this. I just finished the chapter last night where it tells you to record quotes you find interesting along with their exact location in a literature note, so that you can return to them with ease at any time. It's one of those chicken-and-egg problems I guess. You needed to read the book first. That said I'm still really struggling to "get it". All I use is Firefox so I see lots of grainy images and no clear feature list. Especially useful would be to contrast the behavior of your package with the default behavior. I only just downloaded org-roam last night and everything in your images looks like what I have been doing in the tutorials. You open another note side-by-side. So do I. Is this just a filter on the iBuffer list so that I only see my open roam notes?

Everything looks similar to org-roam because it uses the core org-roam functions for its completions. The difference is that it has filter functions to only show the things you want. Thats the core idea, filter completions to what you want and then start inserting those things in a separate buffer to reas them.

I'm starting to get it. I use projectile in conjunction to perspective.el. I assumed that your functionality was covered by those projects, but I can see that your idea is more flexible and roam-specific.

Yeah, I was initially considering building this on top of projectile, but that seemed like it would give me more limitations in what I can do. If you have any questions feel free to contact me

I read the introduction. I understand the intentions, but I can't really say what the packagen actually do.

Select some buffers/org-roam nodes from a completion menu, filter your switch-to-buffer and org-roam-node-find to show only those and then be able to insert their contents in a seperate buffer to make an outline of the topic in question. Do you have any suggestions to make it clearer maybe?

Yeah, copy exactly what you just wrote, make it a little more presentable and put it in the beginning of the introduction ;)

Ok, done!

I can't see what was commented originally but I would like to say, I really think that the GIF are very useful. I am a very visual learner so seeing how the package workflow is used by the creator is priceless for someone like me and is literally the first thing I look at when looking at an Emacs packages' gitlab/hub page.

Hello again, I found the quote and added it to the introduction as an epigraph of sorts. If you have the time feel free to check it out

Hot diggity, that introduction helps me understand the purpose and intention of this package. I love the idea of the right and proper "desktop"

Glad to hear that mate!