20
submitted 2 years ago* (last edited 2 years ago) by nutomic@lemmy.ml to c/asklemmy@lemmy.ml

My current task is to improve the Lemmy documentation, particularly to explain things better for people who are new to Lemmy and the Fediverse. For this I would like to know if there are any things that were unclear when you first joined (or even still unclear now).

To give you some idea, these are the pages which I plan to write for the first section, with average users in mind:

  • Getting started (choose an instance, register, follow, setup profile, start posting)
  • What is federation
  • Moderation
  • Censorship resistance
  • Votes and ranking
  • Media (Markdown, images, links)
  • Other features (theming, language tags, ...)

Besides this I also plan to improve other parts of the documentation, to add things like documentation for the HTTP API (currently only exists for websocket), a guide to run Lemmy with TOR, and explanation of community/site options. Is there anything else where documentation is missing or requires clarification?

By the way, just like other parts of Lemmy the documentation is open source, and you are welcome to open pull requests with improvements.

top 17 comments
sorted by: hot top controversial new old
[-] raubarno@lemmy.ml 5 points 2 years ago

@nutomic Idk if this stands for the 'documentation', more like a guide. I don't know, I didn't need a guide, but I'm a power user, just experimenting in the wild. For the end users, I guess there should be as little documentation as possible. Idk, it might be more challenging to do, but a javascripty interactive tour over the Lemmy would do its job.

[-] rhymepurple@lemmy.ml 5 points 2 years ago

This is a great initiative. Based on the areas listed in the post, it seems like the focus is primarily targeted towards end users instead of administrators or moderators. If that's the intent, making the docs more "accessible" (ie more links to the docs, more mentions of the docs on places like join-lemmy.org) may be helpful, especially if the docs are mentioned as more than just technical documentation (eg FAQs, More Info, Learn More, etc.).

One thing that is still a little unclear to me is how communities with the same name are handled. For example, if there is a community called popular_community created on three different Lemmy instances, will a Lemmy user subscribing to one instance's popular_community automatically subscribe the Lemmy user to the other two instances' popular_community (assuming the instances are federated with each other, the user hasn't blocked the other instances, etc.)? What if a Mastodon user (or another non-Lemmy Fediverse user) does that instead of a Lemmy user? If someone tags/mentions/etc. one of instance's popular_community, will the tag/mention/etc. appear on the community within the other instances? What if a Lemmy user subscribes to more than one popular_community and gets banned from one? Is there a way to prevent multiple communities with the same name across Lemmy instances or to make one instance's community systemically recognized as the "official" community (short of reaching out to each community's moderators/administrators to manually link to the single "official" community)? What happens if one instance's administrator shuts down or removes it's instance's popular_community ? How do any of these answers change depending on which Lemmy instance the Lemmy user registers on (if any change at all)?

[-] nutomic@lemmy.ml 3 points 2 years ago

Communities work in the same way as users, so like you can have @alice@mastodon.social and @alice@lemmy.ml which are completely independent from each other, its the same way with [!popular_community@lemmy.ml](/c/popular_community@lemmy.ml) and [!popular_community@feddit.de](/c/popular_community@feddit.de). The software platform doesnt make any difference. The reason for this is that the ID of a federated user or community is not just the name, but the name@instance.

It also makes sense to include more documentation links on the website.

[-] rhymepurple@lemmy.ml 2 points 2 years ago

That aligns with how I thought communities should work, but I also thought I've seen behavior on the web app/website that differed from that at some point. Maybe I'm misremembering or the situation was slightly different and didn't pay close enough attention to realize what was happening (eg a post in [!popular_community@lemmy.ml](/c/popular_community@lemmy.ml) that mentions [!popular_community@feddit.de](/c/popular_community@feddit.de) or just searching for popular_community and seeing posts from multiple instances' popular_community).

Hopefully the feedback in this thread is helpful! It seems like there are some good recommendations.

[-] nutomic@lemmy.ml 2 points 2 years ago* (last edited 2 years ago)

Sure if you only search popular_community then the results will include anything that matches the string. And yes its definitely helpful.

[-] miguel@lemmy.ml 4 points 2 years ago

Basically divide it in two main sections: for USERS and for DEVELOPERS. The first one like a guide/manual: about how this platform works for the average user (less tech stuff), graphical content, clients, etc. And the second one like a documentation/resources module: about how the platform works in-depth (API, Frontend/Backend dev, etc.).

[-] nutomic@lemmy.ml 3 points 2 years ago

Its already divided like that, but using "For users", "For developers" etc as section titles sounds like a good idea.

[-] Aria@lemmygrad.ml 3 points 2 years ago

For this I would like to know if there are any things that [are] still unclear now.

I'm registered on Lemmygrad. Lemmygrad and Lemmy are federated, I see this post. How come I can't see all Lemmy.ml communities? Is that Lemmygrad's decision? Is that something I could override with a different Lemmy client, but without having to register in the Lemmy.ml instance?
As reference, the community librewolf is not accessible from Lemmygrad.ml.

[-] nutomic@lemmy.ml 5 points 2 years ago

Communities are not federated to other instances by default, you need to fetch them first. So you can paste [!librewolf@lemmy.ml](/c/librewolf@lemmy.ml) (or the community url) in the search bar on lemmygrad. Then lemmygrad will fetch the community from lemmy.ml, and you can interact with it normally.

[-] Aria@lemmygrad.ml 5 points 2 years ago

Do any mechanisms exist for letting users discover communities on other instances? Especially brand new ones.

[-] nutomic@lemmy.ml 2 points 2 years ago

No, and I think this might be a bad idea. It would be necessary to federate all communities from all instances, including posts and comments. Thats a lot of data which needs to be stored forever.

[-] TechGuru_007@lemmy.ml 2 points 2 years ago
[-] nutomic@lemmy.ml 3 points 2 years ago

They are listed on join-lemmy.org. But maybe documentation would be a better place? Same goes for about.

[-] Helix@feddit.de 2 points 2 years ago

The API and protocol would be the most important for me. Admin documentation (how to run things) would be second on my wishlist.

[-] nutomic@lemmy.ml 3 points 2 years ago

Is there anything specific that you want the documentation to explain?

load more comments
view more: next ›
this post was submitted on 02 Apr 2023
20 points (100.0% liked)

Asklemmy

43623 readers
940 users here now

A loosely moderated place to ask open-ended questions

Search asklemmy 🔍

If your post meets the following criteria, it's welcome here!

  1. Open-ended question
  2. Not offensive: at this point, we do not have the bandwidth to moderate overtly political discussions. Assume best intent and be excellent to each other.
  3. Not regarding using or support for Lemmy: context, see the list of support communities and tools for finding communities below
  4. Not ad nauseam inducing: please make sure it is a question that would be new to most members
  5. An actual topic of discussion

Looking for support?

Looking for a community?

~Icon~ ~by~ ~@Double_A@discuss.tchncs.de~

founded 5 years ago
MODERATORS