ieure

not exactly a video tutorial, but i have to say that the interactive tutorial is something i really like. thanks. :P

I know The Kids These Days love a video tutorial, but they tend to be made by people who are enthusiastic, but not experts, and are not the best source of information. Reading the official documentation is faster and more accurate.

There's no substitute for building expertise by doing.

would you suggest using emacs in terminal or the “display” version?

I strongly recommend the GUI version over the terminal version. Terminals have a rather limited interaction model which is a hindrance to using some of Emacs' more advanced features, like displaying images, using different typefaces, and using all the key combinations Emacs supports.

You can start here: https://www.gnu.org/software/emacs/tour/

And if you launch Emacs and press C-h t — that is, press Control-H, release them, then press t — it launches the built-in, interactive tutorial.

Funny, I was just the other day appreciating that Lemmy didn't try to open in a new tab.

The interpreter is completely single-threaded, so there's nothing to have a lock over.

Probably the direction will be for more packages to use threads.

They currently don't run in parallel — they're just sugar over the existing cooperative multitasking model — but hopefully they'll get that ability in the future.

Well, I can see that this isn't going to be a productive conversation, so I'm out.

I'll just leave you with this: you have two people here who agree that docs need significant work, and I gave a detailed list of specific things that need addressing. Ignoring half the issues to say, essentially, "you're wrong, just click around" is not helpful.

Several ways:

• They don't simply describe the API. The description of the API is embedded in a particular (JavaScript) implementation of the API client.
• There are almost no textual descriptions of anything, and the ones that do exist are useless, because all they do is repeat the name of the function. For example, the full documentation for deleteCommunity() is "Delete a community." In what circumstances may I delete a community? What authentication needs to be performed before this function is called? What response should I expect if the deletion failed?
• The actual payload structs all have almost no documentation. What's the difference between DeleteCommunity and RemoveCommunity? Okay, so only an admin can remove a community, but like... what do these things actually do?
• There's no place to see everything about an endpoint: its URL, request/response types, etc. It's strewn all over the place, making it harder to find. likePost tells you part of the URL, and the method. You have to click through to CreatePostLike to see the shape of the request body, and PostResponse (and then PostView) to see the expected response... but only on success. For errors, I have no idea. I got down into wrapper(), but it looks like it simply may not implement error handling at all. Figuring out the URL is another slog, this time through buildFullUrl() and the constructor.

In short: The API isn't really documented, and building a new API client requires reverse engineering the JavaScript one.

Before we used to manually maintain other API docs, and it was a huge hassle to keep them updated.

Certainly, writing documentation is work. But the decision to stop doing it externalizes and multiplies the hassle -- it shifts from the Lemmy developers needing to maintain documentation once, to any programmer wishing to interact with Lemmy needing to RE the JS client, every time.

Autogenerating Swagger documentation may be one way to reduce the burden on the Lemmy maintainers.