User guide grammar fixes (#310)

* docs: improve Markdown example display

* docs: improve wording and grammar

* docs: break up large blocks of text into sections

* docs: capitalize headers and start nested headers from H1

* chore: run `prettier`

* docs: italicize administrator and moderator abbreviations
This commit is contained in:
A 2024-05-17 01:24:33 +01:00 committed by GitHub
parent b6fd7ec217
commit 76c8186fc4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 57 additions and 49 deletions

View file

@ -1,4 +1,4 @@
## Choosing an instance
# Choosing an Instance
If you are used to sites like Reddit, then Lemmy works in a fundamentally different way. Instead of a single website like reddit.com, there are many different websites (called _instances_). These are operated by different people, have different topics and rules. Nevertheless, posts created in one instance can directly be seen by users who are registered on another. Its basically like email, but for social media.
@ -6,7 +6,7 @@ This means before using Lemmy and registering an account, you need to pick an in
[instance list screenshot]
## Registration
# Registration
Once you choose an instance, it's time to create your account. To do this, click _sign up_ in the top right of the page, or click the top right button on mobile to open a menu with _sign up_ link.
@ -29,7 +29,7 @@ When you are done, press the _sign up_ button.
It depends on the instance configuration when you can login and start using the account. In case the email is mandatory, you need to wait for the confirmation email and click the link first. In case "Question/Answer" is present, you need to wait for an admin to manually review and approve your registration. If you have problems with the registration, try to get in contact with the admin for support. You can also choose a different instance to sign up if your primary choice does not work.
## Following communities
# Following Communities
After logging in to your new account, its time to follow communities that you are interested in. For this you can click on the _communities_ link at the top of the page (on mobile, you need to click the menu icon on the top right first). You will see a list of communities which can be filtered by subscribed, local or all. Local communities are those which are hosted on the same site where you are signed in, while _all_ also contains federated communities from other instances. In any case you can directly subscribe to communities with the right-hand subscribe link. Or click on the community name to browse the community first, see what its posted and what the rules are before subscribing.
@ -37,7 +37,7 @@ Another way to find communities to subscribe to is by going to the front page an
These previous ways will only show communities that are already known to the instance. Especially if you joined a small or inactive Lemmy instance, there will be few communities to discover. You can find more communities by browsing different Lemmy instances, or using the [Lemmy Community Browser](https://browse.feddit.de/). When you found a community that you want to follow, enter its URL (e.g. `https://feddit.de/c/main`) or the identifier (e.g. `!main@feddit.de`) into the search field of your own Lemmy instance. Lemmy will then fetch the community from its original instance, and allow you to interact with it. The same method also works to fetch users, posts or comments from other instances.
## Setting up your profile
# Setting up Your Profile
Before you start posting, its a good idea to provide some details about yourself. Open the top-right menu and go to "settings". Here the following settings are available for your public profile:
@ -53,7 +53,7 @@ On this page you can also change the email and password. Additionally there are
- **Interface language**: Which language the user interface should use.
- **Languages**: Select the languages that you speak to see only content in these languages. This is a new feature and many posts don't specify a language yet, so be sure to select "Undetermined" to see them.
- **Theme**: You can choose between different color themes for the user interface. Instance admins can add more themes.
- **Type**: Which timeline you want to see by default on the frontpage; only posts from communities that you subscribe to, posts in local communities, or all posts including federated.
- **Type**: Which timeline you want to see by default on the front page; only posts from communities that you subscribe to, posts in local communities, or all posts including federated.
- **Sort type**: How posts and comments should be sorted by default. See [Votes and Ranking](03-votes-and-ranking.md) for details.
- **Show NSFW content**: Whether or not you want to see content that is "not safe for work" (or adult-only).
- **Show Scores**: Whether the number of upvotes and downvotes should be visible.
@ -64,10 +64,10 @@ On this page you can also change the email and password. Additionally there are
- **Show Notifications for New Posts**: Enable this to receive a popup notification for each new post that is created.
- **Send notifications to Email**: Enable to receive notifications about new comment replies and private messages to your email address.
## Start posting
# Start Posting
Finally its time to start posting! To do this it is always a good idea to read the community rules in the sidebar (below the _Subscribe_ button). When you are ready, go to a post and type your comment in the box directly below for a top-level reply. You can also write a nested reply to an existing comment, by clicking the left-pointing arrow.
Other than commenting on existing posts, you can also create new posts. To do this, click the button _Create a post_ in the sidebar. Here you can optionally supply an external link or upload an image. The title field is mandatory and should describe what you are posting. The body is again optional, and gives space for long texts. You can also embed additional images here. The _Community_ dropdown below allows choosing a different community to post in. With _NSFW_ posts can be marked as "not safe for work". Finally you can specify the language that the post is written in, and then click on _Create_.
Other than commenting on existing posts, you can also create new posts. To do this, click the button _Create a post_ in the sidebar. Here you can optionally supply an external link or upload an image. The title field is mandatory and should describe what you are posting. The body is again optional, and gives space for long texts. You can also embed additional images here. The _Community_ dropdown below allows choosing a different community to post in. With _NSFW_, posts can be marked as "not safe for work". Finally you can specify the language that the post is written in, and then click on _Create_.
One more possibility is to write private messages to individual users. To do this, simply visit a user profile and click _Send message_. You will be notified about new private messages and comment replies with the bell icon in the top right.

View file

@ -1,4 +1,4 @@
## Text
# Text
The main type of content in Lemmy is text which can be formatted with Markdown. Refer to the table below for supported formatting rules. The Lemmy user interface also provides buttons for formatting, so it's not necessary to remember all of it. You can also follow the interactive [CommonMark tutorial](https://commonmark.org/help/tutorial/) to get started.
@ -11,34 +11,34 @@ The main type of content in Lemmy is text which can be formatted with Markdown.
| \[Link\](http://a.com) | \[Link\]\[1\]<br><br>\[1\]: http://b.org | [Link](https://commonmark.org/) |
| !\[Image\](http://url/a.png) | !\[Image\]\[1\]<br><br>\[1\]: http://url/b.jpg | ![Markdown](https://commonmark.org/help/images/favicon.png) |
| \> Blockquote | | <blockquote>Blockquote</blockquote> |
| \* List <br>\* List <br>\* List | \- List <br>\- List <br>\- List <br> | _ List <br>_ List <br>\* List <br> |
| 1\. One <br>2\. Two <br>3\. Three | 1) One<br>2) Two<br>3) Three | 1. One<br>2. Two<br>3. Three |
| \* List <br>\* List <br>\* List | \- List <br>\- List <br>\- List <br> | <ul><li>List</li><li>List</li><li>List</li></ul> |
| 1\. One <br>2\. Two <br>3\. Three | 1) One<br>2) Two<br>3) Three | <ol><li>One</li><li>Two</li><li>Three</li></ol> |
| Horizontal Rule <br>\--- | Horizontal Rule<br>\*\*\* | Horizontal Rule <br><hr> |
| \`Inline code\` with backticks | | `Inline code` with backticks |
| \`\`\`<br>\# code block <br>print '3 backticks or'<br>print 'indent 4 spaces' <br>\`\`\` | ····\# code block<br>····print '3 backticks or'<br>····print 'indent 4 spaces' | \# code block <br>print '3 backticks or'<br>print 'indent 4 spaces' |
| \`\`\`<br>\# code block <br>print '3 backticks or'<br>print 'indent 4 spaces' <br>\`\`\` | ····\# code block<br>····print '3 backticks or'<br>····print 'indent 4 spaces' | <pre><code># code block<br>print '3 backticks or'<br>print 'indent 4 spaces'</code></pre> |
| ::: spoiler hidden or nsfw stuff<br>_a bunch of spoilers here_<br>::: | | <details><summary> hidden or nsfw stuff </summary><p><em>a bunch of spoilers here</em></p></details> |
| Some \~subscript\~ text | | Some <sub>subscript</sub> text |
| Some \^superscript\^ text | | Some <sup>superscript</sup> text |
[CommonMark Tutorial](https://commonmark.org/help/tutorial/)
## Images and video
# Images and Video
Lemmy also allows sharing of images and videos. To upload an image, go to the _Create post_ page and click the little image icon under the _URL_ field. This allows you to select a local image. If you made a mistake, a popup message allows you to delete the image. The same image button also allows uploading of videos in .gif format. Instead of uploading a local file, you can also simply paste the URL of an image or video from another website.
Note that this functionality is not meant to share large images or videos, because that would require too many server resources. Instead, upload them on another platform like [PeerTube](https://joinpeertube.org/) or [Pixelfed](https://pixelfed.org/), and share the link on Lemmy.
## Torrents
# Torrents
Since Lemmy doesn't host large videos or other media, users can share files using [BitTorrent](https://en.wikipedia.org/wiki/BitTorrent) links. In BitTorrent, files are shared not by a single user, but by _many users_ at the same time. This makes file sharing efficient, fast, and reliable, as long as several sources are sharing the files.
Lemmy supports posting torrent magnet links (links that start with `magnet:`) in the post _URL_ field, or as markdown links within comments.
Lemmy supports posting torrent magnet links (links that start with `magnet:`) in the post _URL_ field, or as Markdown links within comments.
With this, Lemmy can serve as an alternative to centralized media-centric services like YouTube and Spotify.
### How to watch Torrents
## How to Watch Torrents
#### Beginner
### Beginner
To easily stream videos and audio on Lemmy, you can use any of the following apps. After clicking on a torrent link in Lemmy, a dialog will pop up asking you to open the link in the app.
@ -47,7 +47,7 @@ To easily stream videos and audio on Lemmy, you can use any of the following app
- [Popcorn Time](https://github.com/popcorn-official/popcorn-desktop) (Desktop)
- [xTorrent](https://play.google.com/store/apps/details?id=com.gamemalt.streamtorrentvideos) (Android)
#### Expert
### Expert
For those who would like to help share files, you can use any of the following torrent clients.

View file

@ -1,8 +1,10 @@
## Votes and ranking
# Posts
Lemmy uses a voting system to sort post listings. On the left side of each post there are up and down arrows, which let you _upvote_ or _downvote_ it. You can upvote posts that you like so that more users will see them. Or downvote posts so that they are less likely to be seen. Each post receives a score which is the number of upvotes minus number of downvotes.
Lemmy uses a voting system to sort post listings. On the left side of each post there are _up_ and _down_ arrows, which let you _upvote_ or _downvote_ it. You can upvote posts that you like so that more users will see them, or downvote posts so that they are less likely to be seen. Each post receives a score which is the number of upvotes minus the number of downvotes.
When browsing the frontpage or a community, you can choose between the following sort types for posts:
## Sorting Posts
When browsing the front page or a community, you can choose between the following sort types for posts:
- **Active** (default): Calculates a rank based on the score and time of the latest comment, with decay over time
- **Hot**: Like active, but uses time when the post was published
@ -15,9 +17,13 @@ When browsing the frontpage or a community, you can choose between the following
- **Top Week**: Highest scoring posts during the last 7 days
- **Top Month**: Highest scoring posts during the last 30 days
- **Top Year**: Highest scoring posts during the last 12 months
- **Top All Time**: Highest scoring posts during all time
- **Top All Time**: Highest scoring posts of all time
Comments are by default arranged in a hierarchy which shows at a glance who it is replying to. Top-level comments which reply directly to a post are on the very left, not indented at all. Comments that are responding to top-level comments are indented one level and each further level of indentation means that the comment is deeper in the conversation. With this layout it is always easy to see the context for a given comment, by simply scrolling up to the next comment which is indented one level less.
# Comments
Comments are by default arranged in a hierarchy which shows at a glance who it is replying to. Top-level comments which reply directly to a post are on the very left, not indented at all. Comments that are responding to top-level comments are indented one level and each further level of indentation means that the comment is deeper in the conversation. With this layout, it is always easy to see the context for a given comment, by simply scrolling up to the next comment which is indented one level less.
## Sorting Comments
Comments can be sorted in the following ways. These all keep the indentation intact, so only replies to the same parent are shuffled around.

View file

@ -1,33 +1,35 @@
## Moderation
# Moderation
The internet is full of bots, trolls and other malicious actors. Sooner or later they will post unwanted content to any website that is open to the public. It is the task of administrators and moderators to remove such unwanted content. Lemmy provides many tools for this, from removing individual posts, over temporary bans, to removing all content from an offending user.
The internet is full of bots, trolls and other malicious actors. Sooner or later they will post unwanted content to any website that is open to the public. It is the task of administrators and moderators to remove such unwanted content. Lemmy provides many tools for this, from removing individual posts and issuing temporary bans, to removing all content submitted by an offending user.
Moderation in Lemmy is divided between administrators and moderators. Admins are responsible for the entire instance, and can take action on any content. They are also the only ones who can completely ban users. In contrast, moderators are only responsible for a single community. Where admins can ban a user from the entire instance, mods can only ban them from their community.
Moderation in Lemmy is divided between administrators (_admins_) and moderators (_mods_). Admins are responsible for the entire instance, and can take action on any content. They are also the only ones who can completely ban users. In contrast, moderators are only responsible for a single community. Whereas admins can ban a user from the entire instance, mods can only ban them from their community.
The most important thing that normal users can do if they notice a rule breaking post is to use the report function. If you notice such a post, click the flag icon to notify mods and admins. This way they can take action quickly and remove the offending content. To find out about removals and other mod actions, you can use the mod log which is linked at the bottom of the page. In some cases there may be content that you personally dislike, but which doesn't violate any rules. For this exists a block function which hides all posts from a given user or community.
The most important thing that normal users can do if they notice a rule-breaking post is to use the report function. If you notice such a post, click the flag icon to notify mods and admins. This way they can take action quickly and remove the offending content. To find out about removals and other mod actions, you can use the mod log which is linked at the bottom of the page. In some cases there may be content that you personally dislike, but which doesn't violate any rules. For this, there is a block function which hides all posts from a given user or community.
Each instance has a set of rules to let users know which content is allowed or not. These rules can be found in the sidebar and apply to all local communities on that instance. Some communities may have their own rules in the respective sidebar, which apply in addition to the instance rules.
## Rules
Each instance has a set of rules to let users know which content is allowed or not. These rules can be found in the sidebar and apply to all local communities on that instance. Some communities may have their own rules in their respective sidebars, which apply in addition to the instance rules.
Because Lemmy is decentralized, there is no single moderation team for the platform, nor any platform-wide rules. Instead each instance is responsible to create and enforce its own moderation policy. This means that two Lemmy instances can have rules that completely disagree or even contradict. This can lead to problems if they interact with each other, because by default federation is open to any instance that speaks the same protocol. To handle such cases, administrators can choose to block federation with specific instances. To be even safer, they can also choose to be federated only with instances that are allowed explicitly.
### How to moderate
## How to Moderate
To get moderator powers, you either need to create a new community, or be appointed by an existing moderator. Similarly to become an admin, you need to create a new instance, or be appointed by an existing instance admin. Community moderation can be done over federation, you don't need to be registered on the same instance where the community is hosted. To be an instance administrator, you need an account on that specific instance. Admins and moderators are organized in a hierarchy, where the user who is listed first has the power to remove admins or mods who are listed later.
To get moderator powers, you either need to create a new community, or be appointed by an existing moderator. Similarly, to become an admin, you need to create a new instance, or be appointed by an existing instance admin. Community moderation can be done over federation, you don't need to be registered on the same instance where the community is hosted. To be an instance administrator, you need an account on that specific instance. Admins and moderators are organized in a hierarchy, where the user who is listed first has the power to remove admins or mods who are listed later.
All moderation actions are taken on the context menu of posts or comments. Click the three dot button to expand available mod actions, as shown in the screenshot below. All actions can be reverted in the same way.
All moderation actions are taken in the context menu of posts or comments. Click the three dot button to expand available mod actions, as shown in the screenshot below. All actions can be reverted in the same way.
![moderation_01.png](moderation_01.png)
![moderation_02.png](moderation_02.png)
| Action | Result | Permission level |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| Lock | Prevents making new comments under the post | Moderator |
| Sticky (Community) | Pin the publication to the top of the community listing | Moderator |
| Sticky (Local) | Pin the publication to the top of the frontpage | Admin |
| Sticky (Local) | Pin the publication to the top of the front page | Admin |
| Remove | Delete the post | Moderator |
| Ban from community | Ban user from interacting with the community, but can still use the rest of the site. There is also an option to remove all existing posts. | Moderator |
| Ban from community | Ban the user from interacting with the community, but they can still use the rest of the site. There is also an option to remove all existing posts. | Moderator |
| Appoint as mod | Gives the user moderator status | Moderator |
| Ban from site | Completely bans the account, so it can't login or interact at all. There is also an option to remove all existing posts. | Admin |
| Ban from site | Completely bans the account, so it cannot log in or interact at all. There is also an option to remove all existing posts. | Admin |
| Purge user | Completely delete the user, including all posts and uploaded media. Use with caution. | Admin |
| Purge post/comment | Completely delete the post, including attached media. | Admin |
| Appoint as admin | Gives the user administrator status | Admin |

View file

@ -1,17 +1,17 @@
## Theming
# Theming
Users can choose between a number of built-in color themes. Admins can also provide additional themes and set them as default.
## Easy to install, low hardware requirements
# Easy to Install, Low Hardware Requirements
Lemmy is written in Rust, which is an extremely fast language. Thats why it has very low hardware requirements. It can easily run on a Raspberry Pi or similar low-powered hardware. This makes it easy to administrate and keeps costs low.
Lemmy is written in Rust, which is an extremely fast language. This is why it has very low hardware requirements. It can easily run on a Raspberry Pi or similar low-powered hardware. This makes it easy to administrate and keeps costs low.
## Language Tags
# Language Tags
Lemmy instances and communities can specify which languages can be used for posting. Consider an instance aimed at Spanish users, it would limit the posting language to Spanish so that other languages can't be used. Or an international instance which only allows languages that the admin team understands. Community languages work in the same way, and are restricted to a subset of the instance languages. By default all languages are allowed (including _undefined_).
Lemmy instances and communities can specify which languages can be used for posting. Consider an instance aimed at Spanish users, it would limit the posting language to Spanish so that other languages can't be used. Or an international instance which only allows languages that the admin team understands. Community languages work in the same way, and are restricted to a subset of the instance languages. By default, all languages are allowed (including _undefined_).
Users can also specify which languages they speak, and will only see content in those languages. Lemmy tries to smartly select a default language for new posts if possible. Otherwise you have to specify the language manually.
## Lemmy as a blog
# Lemmy as a Blog
Lemmy can also function as a blogging platform. Doing this is as simple as creating a community and enabling the option "Only moderators can post to this community". Now only you and other people that you invite can create posts, while everyone else can comment. Like any Lemmy community, it is also possible to follow from other Fediverse platforms and over RSS. For advanced usage it is even possible to use the API and create a different frontend which looks more blog-like.
Lemmy can also function as a blogging platform. Doing this is as simple as creating a community and enabling the option "Only moderators can post to this community". Now only you and other people that you invite can create posts, while everyone else can comment. Like any Lemmy community, it is also possible to follow from other Fediverse platforms and over RSS. For advanced usage, it is even possible to use the API and create a different frontend which looks more blog-like.