Consider using nvim's built-in documentation system

[savq]

Hi,

I've been using Lush for a little while and I've been loving it so far, however I've found it inconvenient to skim through the readme to find info I don't remember.

I'd like to suggest using the built-in doc system instead of listing everything in the readme. This would make it a bit easier to navigate and find stuff while working in a color scheme without much "context switching".

More generally, I think the documentation is a bit spread out, with duplicated information in the readme, the two tutorials and the examples.

I'd also be interested in contributing this myself, helping to move the existing info and such. Let me know what you think.

[rktjmp]

Yep, I agree this is a shortfall.

I didn't want to have to maintain two sets of docs (awkward is better than outdated/incorrect) while things were still a bit fluid, but now I think it would be OK.

I have looked into generating vimdocs from markdown before, but I don't think a straight readme.md conversion would be a good option.

Would you want to see for example, the descriptions of what rotating a HSL colour means (triads, complementary, etc) or simply that you can call rotate(0-360) or ro? I would lean towards the vimdoc being a slim API doc.

I also wouldn't mind feedback on the tutorial and quickstart. Is the tutorial too long? or are some examples unclear? It is awkward maintaining both, but basically the quickstart intention was to basically be an 2 minute ad, while the tutorial should act as the main introduction for actually working with lush in a "progressive learning" style.

Maybe that was over engineering it. The quickstart could almost be a gif, but there is also something (at least to me) a bit magical when you turn on the live updater and are able to interact with your changes. I think it's a good way to "sell" lush, for whatever that's really worth.

[rktjmp]

Actually, looking at the root issue, not remembering how to use Lush. I had actually hoped the API would be simple enough that you "wouldn't really need any docs".

Obviously this isn't actually possible in any real context, but I guess I'm wondering it you feel some parts of the API are confusing or if it's just normal human "what was it again" kind of stuff?

[savq]

Would you want to see for example, the descriptions of what rotating a HSL colour means (triads, complementary, etc) or simply that you can call rotate(0-360) or ro?

I think the latter would be better. Either the docs or the readme can point to other resources on Color Theory, but the docs should assume one knows the basics.

Is the tutorial too long?

I would say the opposite, the long tutorial isn't that long (without counting the list of highlights at the end), so having just one should be enough.

\ About the API, I actually found it to be very easy to use. But there are other parts of the "workflow" that are easier to forget, like compiling to normal VimL, which is a very neat feature, but it's kinda buried at the bottom of the readme. This is why the docs work so well, they make all info equally accessible.

I think having a comprehensive documentation; and a shorter, more opinionated readme should be useful for both beginners, and folks more familiar with the plugin, and that's what I'd like to work on for now. Once that's done, you could review that, and decide if the tutorials should be merged together.

I'll try to make a draft of the thing in the next few days, and hopefully it'll make more sense 😅

[rktjmp]

Yeah I was thinking it could be split up when I was reviewing it.

The readme could just include the basics of:

• Install
• "run this for the tutorial"
• "lush is HSL lib and spec/runner"
• "heres what a sample spec looks like"
• go here for more detailed guide or run :h lush etc.

Then link out to the vim doc file for API and other notes, though I might want to still include the the docs in a md format (cross-compiled in whatever direction is easier), I find them nicer to read, especially if you're just cruising github.

I would like to keep a short example of HSL rotate et al in the main readme, as I think most people are more familiar with rgb or hex and need some example to "sell" them on why HSL is good and not actually scary or hard to learn (imo?).

[rktjmp]

See 6168a19c5ed9aca480773578f2c3056b793be501. Sorry it took so long to get through.

It's just the vim-doc part, no readme rewrite.

[rktjmp]

Er... this commit is more useful... cbc95ed64a6c4cf76550fc4aee4e754000cff13d

[savq]

That looks pretty good.

I drafted a new readme in a seperate branch here. The idea is to split the sections on the readme in a more step-by-step fashion, rather than listing the same sections as the docs.

[savq]

I also thought some of the things in the Additional Information section could be added to a wiki. The TODO and Changelog sections could also be on their own file.

[rktjmp]

I would rather keep things in files than the wiki to keep the repo atomic. At least AFAIK they are not pushed into the repo like gh-actions would be.

But yes, it should have a TODO.md and CHANGELOG.MD. I made some notes in #7. Thanks for this I was finding it difficult without another perspective.

[rktjmp]

Fixed 6168a19c5ed9aca480773578f2c3056b793be501, thanks for the help @savq.

[savq]

No problem. Thanks to you for working on Lush!