Document the API

[jaydenseric]

The API is not entirely documented in the readme.

Let's take the async API for example. I actually recalled hearing of some sort of way to do async rendering, and wanted to see if that can be used to better demo race conditions for here. So lets see what the developer experience is trying to figure out how to use the async API...

Firstly, the readme of this repo searching "async":

There's a file called async, lets see what's in it:

Not helpful. Lets see what else is in the readme about "async":

No documentation for what the exported async utilities are or how to use them, maybe there is some documentation at https://github.com/WebReflection/uhooks-dom (not hyperlinked, so lets manually type in the repo URL to look at it):

No documentation here either. Lets see if there is any at https://github.com/WebReflection/uhooks-fx (also not hyperlinked, so lets manually type in the repo URL to look at it):

No documentation here either. Lets try the mentioned https://github.com/WebReflection/uhooks (also not hyperlinked, so lets manually type in the repo URL to look at it):

Now we're getting somewhere. But what is a hooked() call? Does that enable hooks when rendering? Doesn't uland automatically have hooks enabled when rendering, so how do we integrate already integrated hooks? What exactly even is an async hook anyway?

There is nothing to see at the final end of the road explaining what this is, or how it's used. But, even if there was documentation in this uhooks package, there are no guarantees that it would apply to uland since the wording in readmes mentioning these other hooks related packages says things like "based on" which doesn't inspire confidence that they are the same, i.e. a dependency. Perhaps they are loosely inspired.

This is an example of what the developer experience for me has been like the last week, really trying to make a solid attempt at using the micro family of packages. Not for profit mind you, but to promote your work in another open source project. Almost nothing is documented, and there is a huge amount of confusingly similar packages that often seem to have large overlapping concerns.

I've given significant time to reporting some problems with the micro API design for context, and from the start the response has been weirdly hostile. That I'm an idiot, doing wrong things, wasting your time. Later you get outraged for some reason that an issue belongs in another one of these myriad of related repos, and instead of using the GitHub issue transfer feature, you close it and lock it. Even you're confused which repo the issue belongs in, since you say uhooks here, and then later say uland-ssr here.

I'm not out to get you, I'm trying to help. I wasn't being disruptive, you asked in that issue for me to share more example code to reproduce the problems, which I was doing. As I explained in comments the context API design issues apply both to the server and client environments, and I just happened to be using the SSR version for reproductions as that's easier for us than making HTML files and firing up the browser.

In my own open source projects with millions of users, I can't recall ever locking someone's issue. I've collaborated on all sorts of GitHub repos over the years, and there are few times I can remember experiencing so much friction or such a hostile reception to participating. Please don't just shoot the messenger, it would be easier for me to just walk away and not leave any constructive feedback. I'm not here for an argument. Reflecting on this experience might help to explain why people are not adopting your frameworks which you're written is something you want to improve upon this year.

[WebReflection]

Let me recap:

• you opened an issue in wrong repository (you used uland-ssr but you opened an issue in uland)
• because of the previous point, I wasn't sure what you were complaining about, but I've opened an issue in the right repository, if useContext was to blame, as hooks, in uland, are a dependency, not part of uland per se
• I took the time to have a look and provided a CodePen example that works without any issue, based on the wrong examples you provided, trying to better understand what was the issue
• I then realized it was all along about uland-ssr, not uland
• because of the previous point, I have moved the discussion in the right repository, opening an issue, flagging the list of things to do in order to solve such issue

The result:

• I need to spend time to read a huge rant
• I am being accused about things I've never said ... "being an idiot"? "wasting my time"? where did you read those, when all I am trying to do is tracking down properly the issue and the work needed to fix it?
• I have never used GitHub transfer feature, but I've mentioned the original issue in both new issues I've opened
• I am being accused to be confused about my libraries, when I've explained that uhooks is about useContext, and uland-ssr is where we should've discussed all this since the beginning
• the issue doesn't apply in the client environment, as demonstrated by the CodePen
• you took the locked conversation as something super bad, while I've promptly opened a new conversation with less noise and points to focus on ... I am being apparently accused of being an asshole for doing that
• I am being accused to be hostile after trying to understand what is it that you are trying to do, and what is it that I should fix

Recap Again:

• you wrote broken examples to start with
• you picked the wrong repository
• you haven't tried even once to help me out with proper examples, I had to come up with something
• you are now insulting me with huge rants about how bad I am at Open Source

This is not how I do Open Source, this is how I do Open Source, and you kinda scored all negatives in both DOs and DONTs points, but on top of that, all minutes needed to read this huge rant are minutes removed from my free time to fix things, so the result is that ... if before I was happy to move the issue in the right place and work on it, now I honestly don't give a damn, because this is not rewarding, this is not fun, this is just outrageous, non respectful, boring, and the opposite of the meaning of collaboration.

That being said, with uland/async there's nothing to document, because it's the exact same API, but anything asynchronous within the flow, gets resolved before outputting a single char, so it solves async component, async interpolations, and that's pretty much it, and literally nothing you should change, except it works for your asynchronous render cases (in uland, 'cause in uland-ssr I've realized it might not be the case, but that's something that will be fixed, eventually, afterward).

Yeah, the documentation could be improved, but thank you for not even trying to help me out even there.

This "contribution" of you didn't start right, and it's going to hell pretty quickly.

I won't tolerate this attitude, insults, or non respectful conversations anymore, so take this as a warning.

Have a lovely weekend 👋