Simplify configuration option documentation?

[skovati]

I recently created a few PRs with small new configuration option changes, and realized that there are four places where options are defined: README.md example setup() call, README.md configuration table, docs/telekasten.txt example setup() call, and finally the actual vim :help options. This has led to documentation fragmentation, e.g. the README.md table is missing options that exist in the :help docs.

One possible solution is to keep the existing example setup() call with defaults in the README.md that can act as a quick-start for new users, and then place all other configuration options in docs/telekasten.txt, which can be the more verbose, single source of truth for all possible options.

tl;dr, maybe we should remove the config table in the README.md and the example setup() call in docs/telekasten.nvim to have a single source of documentation truth.

[lambtho12]

Totally agree with you here. We already had a similar discussion a while back (#75) and started doing the wiki, but @renerocksai and I were both rather busy with our jobs the last two quarters and doc has definitely not the main focus point for the few hours we were able to spare for working on TK.

I am definitely in favor for a lighter and more comprehensive readme. I do not even think all options should be in there, only the minimal configurations (setup home directory for instance) and some sane mappings. For inspiration, we could see how it is done for vimtex for instance. It also has a ton of options but does not completely submerge the reader with all possibilities.

As you said, docs/telekasten.txt must be the single source of truth. After that, README.md should just contain the basic configuration for how to quick start using telekasten. The wiki can then be used for more advanced options (create custom mappings by manipulating the lua function's arguments), etc. With such a setup, only the docs/telekasten.txt file would require regular maintenance. The rest would be more or less set-and-forget.

To make everything more easily manageable, I also think that the defaults options used in the setup() may benefit from being refactored in a separate lua/telekasten/defaults.lua file.

[renerocksai]

Re sourcehut: To be honest, I don't feel that strongly about moving
Telekasten to SH anymore. When the whole issue came up and was still
hot, my initial reaction was strong and passionate. Now, time has
passed, I can see things from a bit more (emotional) distance, and I am
having a few doubts.

Mainly / aside: As much as I would like, I am currently not involved
that actively in telekasten development. I am amazed though by how well
you, @lambtho12, manage the whole situation - and by the quality of some
contributions coming in. I have always feared that due to the (also
improved but still a bit) quick-hack-organization of the code,
contributions would introduce more side-effects than they actually have
and that recently it seems you had an eye specifically for preventing
from unintended side-effects to creep in.

But what being not that active also means is: other people are doing the
real work, not me. So, naturally, when they invest their precious time,
it should a) be worth it, b) be honored, and c) they should have some
say regarding changing to a platform that probably isn't as intuitive
for them, at least initially. We have seen pretty strong reactions
suggesting staying on GH. While I don't agree with (all of the)
arguments being made, I respect and acknowledge that there are strong
feelings. Not alienating most of the contributors is maybe something I
should think about.

Now, back to sourcehut: I love it and use it for all my new repos and
for my less public projects - and don't want to start anything new on
GitHub. However, I am thinking about things like: maybe it's worth to
keep on GH what started on GH. "The community" seems to love their
GitHub with all its stars and PRs. Seing that we're in the region of ca.
650 stars now, with 21 contributors - I cannot really argue that it's
just my little plugin. It has become a community effort.

Also, I have to admit: people find TK on GH, and then, kind of
naturally, want to contribute via GH. Trying to force "alien" workflows
on everybody is maybe not the best idea, as much as I would like
everyone to just see that there are better alternatives like on
sourcehut.

In addition, even with 650 stars, TK is a very small project. We're not
likely to change a lot of minds by forcing the move to sourcehut. Also,
I think it's unlikely that TK itself is exploited a lot if its code
finds its way into Copilot. While I still hate GH for doing what they
do: it doesn't directly affect my life in the slightest. It's just a few
lines of lua in a way. I don't feel so super strongly about the issue at
hand anymore - and would like to focus more on the technical side of
things, without much politics and stuff.

So, trying to sum up my thoughts: I don't know. There are strong
arguments pro and con. If I want to minimize extra work, then staying on
GH seems like a good idea. It also seems to save us from a lot of "what
is this? how do I contribute here?" and other SH-related questions.

GH seems to be the expected thing for most users and contributors.

I'll stop rambling now.

BTW Re not being that active: My new year's resolution is to have an
"open source" session of a few hours at least once a week where I also
plan to check on telekasten. Waiting until work stress is reliefed has
proven to be totally unrealistic.

And: I still can't stand this shitty web interface, especially for
discussions. So I'd still like to switch to a sourcehut-powered mailing
list for them. Maybe a GitHub / SourceHut hybrid would work well for
telekasten?

What do you think?

[lambtho12]

First of all, thank you very much for you nice words. I am happy to help keep the project alive (with the tremendous help of all other contributors) while we all wait for your great return. 😄

I completely agree with your train of thoughts here. While I did not have any personal project on GH myself (I use Gitlab), it seems that I ended up where you are too. I did not move my public projects from Gitlab, but I moved all personal projects on sourcehut and plan on using it for my next projects.

So should I just stop to maintain the SourceHut stuff and remove everything related to that from here to avoid future confusion ? Maintaining both repos is typically not a big deal for small PRs, but it might become cumbersome when we start refactoring big chunks. I'd rather avoid wasting the very little time I have on my hand for such tasks.

[skovati]

Is it possible to set up some sort of automated repo mirroring? IIRC Gitlab has such a feature.

I'd like to see the project move to sr.ht for philosophical reasons, but I agree that Github has become the best place to discover new software, so plugin exposure would likely be a lot higher if we stayed on Github.

[renerocksai]

@lambtho12, I'll shoot from the hip and make a quick decision: sourcehat's off for Telekasten. Please don't waste any more of your time on it any longer. (disclaimer: I still like and prefer Sourcehut - if anyone tries to misread this message and frame it as anti sourcehut 😄).

I agree, the links to sourcehut should be removed, good idea. I also think that maybe we could move the "We're using GitHub under protest" more towards the end of the readme or, to be congruent with our actions: remove it entirely. Saying "I don't want to be here" and then staying there is a bit silly to be frank. If we really don't want to stay here we should leave and not just put a claim somewhere.

@skovati I agree on the philosophical reasons. But in this case, the pragmatic way won. It's not just about discoverability for me but also about avoiding putting up extra hurdles / friction for potential contributors who, by a majority, seem to be really set in doing stuff the GH way.

I'd still like to disable discussions if possible and move them to a mailing list on sourcehut.

[skovati]

Works for me! If we don't have to worry about SH parity, then I'll go ahead and start some documentation refactoring; I should have time this weekend.

[lambtho12]

@skovati , I started working on a big cleanup of the README, see the branch https://github.com/renerocksai/telekasten.nvim/tree/readme-cleanup. What do you think about it?

[skovati]

Looks good! I like having the dead simple quickstart first and then having more advanced configuration like calendar and image previews below. I also love the idea of replacing images with a gif showing some of the features; it reduces the visual clutter of the readme.

[skovati]

Somewhat related, I also have a working branch on my fork that refactors the defaults into their own lua module.
https://github.com/skovati/telekasten.nvim/tree/refactor_defaults

[lambtho12]

Looks good! I like having the dead simple quickstart first and then having more advanced configuration like calendar and image previews below. I also love the idea of replacing images with a gif showing some of the features; it reduces the visual clutter of the readme.

Awesome. I will update a bit the doc/telekasten.txt as well to make sure nothing is lost in the process. Then I will push all that.
I will make the gif afterwards, I have to see how to do it first and think of a good workflow to showcase.

Somewhat related, I also have a working branch on my fork that refactors the defaults into their own lua module. https://github.com/skovati/telekasten.nvim/tree/refactor_defaults

Really nice, feel free to push small PRs with refactoring stuff or make a big refactoring PR. I think this is desperately needed to make more people collaborate on TK and simplify the maintenance and deployment of new features.