AkkomaGang/akkoma
AkkomaGang
/
akkoma
12
63
Fork 83
Code Issues 173 Pull Requests 14 Packages Projects 2 Releases 12 Wiki Activity

Docs: Fix typos #525

Open
solidsanek wants to merge 9 commits from solidsanek/akkoma:fix-docs-typo into develop
pull from: solidsanek/akkoma:fix-docs-typo
merge into: AkkomaGang:develop
Conversation 5 Commits 9 Files Changed 65 +644 -700
solidsanek commented 2023-04-22 22:13:04 +00:00
First-time contributor
Copy Link

I started by wanting to fix one typo, and then I noticed there were other typos, and then things kinda snowballed from there.

I guess it works fine as it is, but I still have questions, like:

  • What about this security.md file? I guess it needs an update
  • There's a lot of inconsistency across the FE names (masto-fe / mastodon-fe / MastoFE / etc.). What do we actually go for, for MastoFE, PleromaFE and AdminFE?
  • In lists, half of the time, elements start with a capitalized letter, the other times it does not, so what do we go for? (this is more of a nitpick though, I guess)
  • In the "mrf_vocabulary" section, talking about "ActivityStreams terms" feel like the kind of technical term that could be replaced with something much simpler to understand

I can't guarantee that I caught all typos and inconsistencies, but this should be an okay start

I started by wanting to fix one typo, and then I noticed there were other typos, and then things kinda snowballed from there. I guess it works fine as it is, but I still have questions, like: - What about this security.md file? I guess it needs an update - There's a lot of inconsistency across the FE names (masto-fe / mastodon-fe / MastoFE / etc.). What do we actually go for, for MastoFE, PleromaFE and AdminFE? - In lists, half of the time, elements start with a capitalized letter, the other times it does not, so what do we go for? (this is more of a nitpick though, I guess) - In the "mrf_vocabulary" section, talking about "ActivityStreams terms" feel like the kind of technical term that could be replaced with something much simpler to understand I can't guarantee that I caught all typos and inconsistencies, but this should be an okay start
solidsanek added 1 commit 2023-04-22 22:13:05 +00:00
ci/woodpecker/pr/woodpecker Pipeline is pending Details
7cf6b40dc5 Docs: Fix typos
ilja reviewed 2023-04-23 14:53:13 +00:00
ilja left a comment
Contributor
Copy Link

This seems like a lot of work! Ty for that!

I added some notes, but also there's one general thing; I see that you changed all the !!! note, !!! warning... to use a capital letter. I wonder if this has been tested. Those are extentions and the docs only provide the examples with lowercase letters[1]. If it still works, then we could indeed change it here, although I would personaly err on the side of lowercase because that's how the docs of the extention show it.

For your points, here's my 2 cents on them:

  • The security.md indeed needs an update. Afaik, there's currently no defined way to do that. Unless that has changed, it's probably best to just remove it. If people want to submit a security thing, they can always ask in chat or something (this has happened recently).
  • For names, I would use the names used in the respective repos. That's akkoma-fe, masto-fe, and admin-fe[2].
  • For lists I would say that if it's the start of a sentence, capitalise. If it's a continuation of a sentence, don't capitalise (unless there's other reasons to capitalise e.g. because we start with a name). If it's neither, no opinion.
  • I agree that "ActivityStreams terms" is technical. But it's also litterally what it does. I'm unsure what to do with it. Maybe provide a list? But if we add support for new types, we'll need to update it. Or link to the spec? But the spec doesn't have everything we support and has things that aren't used as such... Idk

I'm also wondering if we should have some notes or style-guide. You did many fixes now, but if we don't write down how thing should be styled, then I'm afraid it will just become a mess again in the future.

[1] https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
[2] https://akkoma.dev/AkkomaGang

This seems like a lot of work! Ty for that! I added some notes, but also there's one general thing; I see that you changed all the `!!! note`, `!!! warning`... to use a capital letter. I wonder if this has been tested. Those are extentions and the docs only provide the examples with lowercase letters[1]. If it still works, then we could indeed change it here, although I would personaly err on the side of lowercase because that's how the docs of the extention show it. For your points, here's my 2 cents on them: * The security.md indeed needs an update. Afaik, there's currently no defined way to do that. Unless that has changed, it's probably best to just remove it. If people want to submit a security thing, they can always ask in chat or something (this has happened recently). * For names, I would use the names used in the respective repos. That's akkoma-fe, masto-fe, and admin-fe[2]. * For lists I would say that if it's the start of a sentence, capitalise. If it's a continuation of a sentence, don't capitalise (unless there's other reasons to capitalise e.g. because we start with a name). If it's neither, no opinion. * I agree that "ActivityStreams terms" is technical. But it's also litterally what it does. I'm unsure what to do with it. Maybe provide a list? But if we add support for new types, we'll need to update it. Or link to the spec? But the spec doesn't have everything we support and has things that aren't used as such... Idk I'm also wondering if we should have some notes or style-guide. You did many fixes now, but if we don't write down how thing should be styled, then I'm afraid it will just become a mess again in the future. [1] <https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types> [2] <https://akkoma.dev/AkkomaGang>
docs/docs/administration/monitoring.md Outdated
@ -4,3 +4,3 @@
and that there's nothing quietly failing in the background.
To facilitate this, akkoma exposes prometheus metrics to be scraped.
To facilitate this, Akkoma exposes Prometheus metrics to be scrapped.
ilja commented 2023-04-23 12:42:05 +00:00
Contributor
Copy Link

Isn't "scraped" (with one "p") correct here?

  • scrapped => to do away with
  • scraped => collect data from a webpage
Isn't "scraped" (with one "p") correct here? * scrapped => to do away with * scraped => collect data from a webpage
solidsanek commented 2023-04-25 20:12:28 +00:00
Author
First-time contributor
Copy Link

Oops, yeah, scraped is the right term, I mixed up the two without verifying them

Oops, yeah, scraped is the right term, I mixed up the two without verifying them
solidsanek marked this conversation as resolved
docs/docs/configuration/cheatsheet.md Outdated
@ -418,1 +415,3 @@
* `ignore_tld`: list TLDs (top-level domains) which will ignore for parse metadata. default is ["local", "localdomain", "lan"].
* `enabled`: if enabled, the instance will parse metadata from attached links to generate link previews.
* `ignore_hosts`: list of hosts which will be ignored by the metadata parser. For example, `["accounts.google.com", "xss.website"]`, defaults to `[]`.
* `ignore_tld`: list TLDs (top-level domains) which will ignore to parse metadata. Default is ["local", "localdomain", "lan"].
ilja commented 2023-04-23 12:55:18 +00:00
Contributor
Copy Link

There's something off about this sentence 🤔. It's similar to the setting above[1], so should probably be more like "list of TLDs (top-level domains) which will be ignored by the metadata parser."

[1] https://akkoma.dev/AkkomaGang/akkoma/src/branch/develop/lib/pleroma/web/rich_media/helpers.ex#L32

There's something off about this sentence 🤔. It's similar to the setting above[1], so should probably be more like "list of TLDs (top-level domains) which will be ignored by the metadata parser." [1] <https://akkoma.dev/AkkomaGang/akkoma/src/branch/develop/lib/pleroma/web/rich_media/helpers.ex#L32>
solidsanek marked this conversation as resolved
docs/docs/configuration/cheatsheet.md Outdated
@ -626,2 +623,3 @@
* `adapter`: one of the mail adapters listed in [Swoosh README](https://github.com/swoosh/swoosh#adapters), or `Swoosh.Adapters.Local` for in-memory mailbox.
* `api_key` / `password` and / or other adapter-specific settings, per the above documentation.
* `enabled`: Allows enable/disable send emails. Default: `false`.
* `enabled`: Allows to enable/disable send emails. Default: `false`.
ilja commented 2023-04-23 13:00:58 +00:00
Contributor
Copy Link

This sentence seems weird too. Maybe "Enable sending emails from your instance." or something?

This sentence seems weird too. Maybe "Enable sending emails from your instance." or something?
solidsanek marked this conversation as resolved
docs/docs/configuration/howto_database_config.md Outdated
@ -44,7 +44,7 @@ The configuration of Akkoma (and Pleroma) has traditionally been managed with a
4. ⚠️ **THIS IS NOT REQUIRED** ⚠️
ilja commented 2023-04-23 13:15:14 +00:00
Contributor
Copy Link

This should probably also use the !!! Note syntax.

4. Strip down the config file

!!! Note
    This step is not required

I also notice that it doesn't actually show the numbering of the steps properly[1]. That's because each step is considered a new list. Not sure what to do with that 🤔

[1] https://docs.akkoma.dev/stable/configuration/howto_database_config/

This should probably also use the `!!! Note` syntax. ``` 4. Strip down the config file !!! Note This step is not required ``` I also notice that it doesn't actually show the numbering of the steps properly[1]. That's because each step is considered a new list. Not sure what to do with that 🤔 [1] <https://docs.akkoma.dev/stable/configuration/howto_database_config/>
solidsanek commented 2023-04-25 21:48:28 +00:00
Author
First-time contributor
Copy Link

Not sure what to do about the step numbers here

Not sure what to do about the step numbers here
Oneric commented 2024-02-01 00:32:12 +00:00
Member
Copy Link

The problem is there’s not enough indentation. Markdown requires following paragraphs to be indented by four spaces to continue a list item, but it currently only uses two spaces.

Here’s a commit on top of this PR fixing it and restoring the 4th list item which seems to have been accidentally deleted while introducing the !!! note block: https://akkoma.dev/Oneric/akkoma/commits/branch/solidsanek__fix-doc-typos
Additionally there’s a commit implementing the “NGINX → nginx” change I suggested below.
Feel free to pick these chnages up and squash them as you like, no need to retain any attribution for me; it was just a sed and a couple spaces anyway.

The problem is there’s not enough indentation. Markdown requires following paragraphs to be indented by four spaces to continue a list item, but it currently only uses two spaces. Here’s a commit on top of this PR fixing it and restoring the 4th list item which seems to have been accidentally deleted while introducing the `!!! note` block: https://akkoma.dev/Oneric/akkoma/commits/branch/solidsanek__fix-doc-typos Additionally there’s a commit implementing the “NGINX → nginx” change I suggested below. Feel free to pick these chnages up and squash them as you like, no need to retain any attribution for me; it was just a `sed` and a couple spaces anyway.
docs/docs/configuration/howto_set_richmedia_cache_ttl_based_on_image.md Outdated
@ -3,3 +3,2 @@
Richmedia are cached without the ttl but the rich media may have image which can expire, like aws signed url.
In such cases the old image url (expired) is returned from the media cache.
Richmedia are cached without the TTL, but the rich media may have image which can expire, like AWS-signed URL.
ilja commented 2023-04-23 13:23:41 +00:00
Contributor
Copy Link

This is maybe more clear/correct: "Rich media is cached without the TTL, but the rich media may have an image which can expire, like AWS-signed URL."

This is maybe more clear/correct: "Rich media is cached without the TTL, but the rich media may have an image which can expire, like AWS-signed URL."
solidsanek marked this conversation as resolved
docs/docs/configuration/howto_theming_your_instance.md
@ -9,3 +9,3 @@
* You can create your own theme using the Pleroma FE by going to settings (gear on the top right) and choose the Theme tab. Here you have the options to create a personal theme.
* To download your theme, you can do Save preset
* If you want to upload a theme to customise it further, you can upload it using Load preset
* If you want to upload a theme to customize it further, you can upload it using Load preset
ilja commented 2023-04-23 13:28:40 +00:00
Contributor
Copy Link

Why the z-spelling over s-spelling? I thought the z-spelling was purely a North America thing. (personally I always try to use the s-spelling.)

Why the z-spelling over s-spelling? I thought the z-spelling was purely a North America thing. (personally I always try to use the s-spelling.)
solidsanek commented 2023-04-25 20:16:25 +00:00
Author
First-time contributor
Copy Link

This change is a bit more opinionated I guess, I noticed that most of the doc wasn't written in British English, except for a couple of exception like "favourite" among a few others, at least from the ones I've spotted. I tend to adapt the spelling depending on which one the docs use primarily. If we consider that British English is the one to prefer, I'll revert these changes and see the spellings I can adapt

This change is a bit more opinionated I guess, I noticed that most of the doc wasn't written in British English, except for a couple of exception like "favourite" among a few others, at least from the ones I've spotted. I tend to adapt the spelling depending on which one the docs use primarily. If we consider that British English is the one to prefer, I'll revert these changes and see the spellings I can adapt
ilja commented 2023-05-21 07:45:19 +00:00
Contributor
Copy Link

I didn't realise the non-British was more prevalent. It indeed makes sense to use the non-British form then. I am opinionated about it, but I'm also just one person, so there's that :p

Edit: I want to mark this as resolved, but I don't see where :/ Maybe gitea doesn't allow that? Anyhow, just to be clear, this (and other similar remarks on British vs American) can be considered resolved for me. The way it was done is correct, no changes needed.

I didn't realise the non-British was more prevalent. It indeed makes sense to use the non-British form then. I am opinionated about it, but I'm also just one person, so there's that :p Edit: I want to mark this as resolved, but I don't see where :/ Maybe gitea doesn't allow that? Anyhow, just to be clear, this (and other similar remarks on British vs American) can be considered resolved for me. The way it was done is correct, no changes needed.
docs/docs/configuration/integrations/howto_ejabberd.md
@ -1,10 +1,10 @@
# Configuring Ejabberd (XMPP Server) to use Akkoma for authentication
# Configuring ejabberd (XMPP Server) to use Akkoma for authentication
ilja commented 2023-04-23 13:34:34 +00:00
Contributor
Copy Link

Here we go to lowercase for the name of a software, I'm wondering what the reasoning is. I see on their site that they also write it with lowercase[1], so I assume that's the reason why we also lowercase it here?

[1] https://www.ejabberd.im/

Here we go to lowercase for the name of a software, I'm wondering what the reasoning is. I see on their site that they also write it with lowercase[1], so I assume that's the reason why we also lowercase it here? [1] <https://www.ejabberd.im/>
solidsanek commented 2023-04-25 20:18:02 +00:00
Author
First-time contributor
Copy Link

Yep. For most software names I've modified, I looked up how the official websites write them, and ejabberd was always written all lowercased, even if it was written at the start of a phrase.

Yep. For most software names I've modified, I looked up how the official websites write them, and ejabberd was always written all lowercased, even if it was written at the start of a phrase.
👍 1
docs/docs/configuration/onion_federation.md Outdated
@ -13,3 +13,3 @@
```
**WARNING:** Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you.
**WARNING:** Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you.
ilja commented 2023-04-23 13:40:55 +00:00
Contributor
Copy Link

Maybe also use the !!! Warning syntax

!!! Warning
    Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you.
Maybe also use the `!!! Warning` syntax ``` !!! Warning Onion instances not using a Tor version supporting V3 addresses will not be able to federate with you. ```
solidsanek commented 2023-04-25 21:01:45 +00:00
Author
First-time contributor
Copy Link

I'll go ahead and change most warnings/notes to !!!, when applicable

I'll go ahead and change most warnings/notes to `!!!`, when applicable
solidsanek marked this conversation as resolved
docs/docs/configuration/optimisation/varnish_cache.md
@ -2,3 +2,3 @@
Varnish is a layer that sits between your web server and your backend application -
it does something similar to nginx caching, but tends to be optimised for speed over
it does something similar to NGINX caching, but tends to be optimized for speed over
ilja commented 2023-04-23 13:42:59 +00:00
Contributor
Copy Link

s- vs z-spelling

s- vs z-spelling
docs/docs/configuration/search.md Outdated
@ -125,3 +125,3 @@
## Elasticsearch
**Note: This requires at least ElasticSearch 7**
**Note: This requires at least Elasticsearch 7**
ilja commented 2023-04-23 13:47:51 +00:00
Contributor
Copy Link

Should probably use !!! Note syntax

Should probably use `!!! Note` syntax
solidsanek marked this conversation as resolved
docs/docs/development/API/admin_api.md Outdated
@ -153,7 +153,7 @@ Backwards-compatibility for admin API endpoints without version prefixes (`/api/
Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
ilja commented 2023-04-23 13:53:43 +00:00
Contributor
Copy Link

Can use !!! Note syntaxt

Can use `!!! Note` syntaxt
solidsanek marked this conversation as resolved
docs/docs/installation/arch_linux_en.md Outdated
@ -9,3 +9,3 @@
### Required packages
* `postgresql`
* `PostgreSQL`
ilja commented 2023-04-23 14:16:58 +00:00
Contributor
Copy Link

I wonder how much sense it makes to capitalise package names here. Backticks generally mean code. So I think it should either be the package name like how you'd use it in a command (pacman -S postgresql), or not be between backticks. For packages I think it make sense to use backticks and the names like how you'd use in commands.

Same for other places.

I wonder how much sense it makes to capitalise package names here. Backticks generally mean code. So I think it should either be the package name like how you'd use it in a command (`pacman -S postgresql`), or not be between backticks. For packages I think it make sense to use backticks and the names like how you'd use in commands. Same for other places.
solidsanek commented 2023-04-25 20:24:00 +00:00
Author
First-time contributor
Copy Link

I believe some of the elements were already capitalised in some ways, which, with the addition of commands below said lists, made me think that it wouldn't be an issue. Now that I look back at these lists, since we're listing packages and not software names, I agree with you

I believe some of the elements were already capitalised in some ways, which, with the addition of commands below said lists, made me think that it wouldn't be an issue. Now that I look back at these lists, since we're listing packages and not software names, I agree with you
solidsanek marked this conversation as resolved
docs/docs/installation/frontends.include
@ -29,3 +29,2 @@
For more customised installations, refer to [Frontend Management](../../configuration/frontend_management)
For more customized installations, refer to [Frontend Management](../../configuration/frontend_management)
ilja commented 2023-04-23 14:21:34 +00:00
Contributor
Copy Link

s- vs z-syntax

s- vs z-syntax
docs/docs/installation/migrating_from_source_otp_en.md Outdated
@ -113,2 +112,3 @@
OTP releases have different service files than from-source installs, so they need to be copied over again.
**Warning:** The service files assume akkoma user's home directory is `/opt/akkoma`, please make sure all paths fit your installation.
**Warning:** The service files assume Akkoma user's home directory is `/opt/akkoma`, please make sure all paths fit your installation.
ilja commented 2023-04-23 14:23:03 +00:00
Contributor
Copy Link

Could probably use !!! Warning syntax

Could probably use `!!! Warning` syntax
solidsanek marked this conversation as resolved
docs/docs/installation/openbsd_en.md Outdated
@ -40,1 +38,3 @@
:openfiles-max=4096
:datasize-max=1536M:\
:datasize-cur=1536M:\
:openfiles-max=4096
ilja commented 2023-04-23 14:28:35 +00:00
Contributor
Copy Link

I see a lot has changed from two indents to one. I have never used *bsd myself. Are we sure that two indents isn't just the typical *bsd way of doing it?

I see a lot has changed from two indents to one. I have never used \*bsd myself. Are we sure that two indents isn't just the typical \*bsd way of doing it?
solidsanek commented 2023-04-25 20:36:58 +00:00
Author
First-time contributor
Copy Link

Ah, I apologize for that one, I accidentally changed the formatting from the tabs it had to spaces. 😅
According to the login.conf files I found, it seems that you're right, I'll revert this

Ah, I apologize for that one, I accidentally changed the formatting from the tabs it had to spaces. 😅 According to the login.conf files I found, it seems that you're right, I'll revert this
solidsanek marked this conversation as resolved
docs/docs/installation/openbsd_en.md Outdated
@ -139,3 +139,3 @@
#### relayd
relayd will be used as the reverse proxy sitting in front of akkoma.
relayd will be used as the reverse proxy sitting in front of Akkoma.
ilja commented 2023-04-23 14:30:59 +00:00
Contributor
Copy Link

Relayd (capital letter because start of sentence)

Relayd (capital letter because start of sentence)
solidsanek marked this conversation as resolved
docs/docs/installation/otp_redhat_en.md Outdated
@ -14,2 +11,3 @@
Important: keep in mind that you must build your OTP release for the specific RedHat distribution you wish to use it on. A build on Fedora will only be compatible with a specific Fedora release version.
In order to compile a RedHat-compatible OTP release, you will need to run a Red Hat Linux distribution. This guide will assume you run Fedora 36, though it should also work on older Fedora releases and other Red Hat distributions. It also assumes that you have administrative rights and sufficient knowledge on how to perform common CLI tasks in Linux. If you want to run this guide with root, ignore the `sudo` at the beginning of the lines.
Important: keep in mind that you must build your OTP release for the specific Red Hat distribution you wish to use it on. A build on Fedora will only be compatible with a specific Fedora release version.
ilja commented 2023-04-23 14:34:12 +00:00
Contributor
Copy Link

Can probably use !!! Important syntaxt.

Can probably use `!!! Important` syntaxt.
solidsanek marked this conversation as resolved
solidsanek commented 2023-04-25 20:11:22 +00:00
Author
First-time contributor
Copy Link

I admit there are quite a bit of elements that I took the liberty of modifying, thinking that it'd fit better. This includes the capitalized letters on !!! note elements, as I was not aware of the tool used to generate these docs. As you mentioned, it's probably safer to revert these changes and keep them lowercased, since the docs write them like so. I'll keep it in mind for any other change.

As for the other points:

  • I might just delete the file as part of the MR, and assume that unless someone provides a better content for said file, it's better to have none than mislead users
  • Sounds good to me for the FE names!
  • That sounds reasonable enough to me. I don't have a strong opinion on these kinds of styling, even though I'd have probably ended up capitalizing them all myself
  • I half expected that if this was named this way, it's because there weren't any other way to explain it. It just felt like it stood out a bit compared to most of the doc I've been reading, as it's more technical

As for the styling guide, I'm not sure how and what would be in it. I feel that it's probably not a bad idea to encourage the use of the elements Mkdocs has, at the very least.

(also thanks for the thoroughness of the feedback, I was just thinking of submitting this as a starter, but there's a lot more that can be done in this MR)

I admit there are quite a bit of elements that I took the liberty of modifying, thinking that it'd fit better. This includes the capitalized letters on `!!! note` elements, as I was not aware of the tool used to generate these docs. As you mentioned, it's probably safer to revert these changes and keep them lowercased, since the docs write them like so. I'll keep it in mind for any other change. As for the other points: - I might just delete the file as part of the MR, and assume that unless someone provides a better content for said file, it's better to have none than mislead users - Sounds good to me for the FE names! - That sounds reasonable enough to me. I don't have a strong opinion on these kinds of styling, even though I'd have probably ended up capitalizing them all myself - I half expected that if this was named this way, it's because there weren't any other way to explain it. It just felt like it stood out a bit compared to most of the doc I've been reading, as it's more technical As for the styling guide, I'm not sure how and what would be in it. I feel that it's probably not a bad idea to encourage the use of the elements Mkdocs has, at the very least. (also thanks for the thoroughness of the feedback, I was just thinking of submitting this as a starter, but there's a lot more that can be done in this MR)
solidsanek added 1 commit 2023-04-25 21:46:10 +00:00
solidsanek added 1 commit 2023-04-25 22:03:46 +00:00
ci/woodpecker/pr/woodpecker Pipeline is pending Details
f43b688ae9 Docs: Don't capitalize package names
solidsanek changed title from Docs: Fix typos to WIP: Docs: Fix typos 2023-04-26 08:18:18 +00:00
solidsanek added 1 commit 2023-04-26 09:05:35 +00:00
ci/woodpecker/pr/woodpecker Pipeline is pending Details
c7b0a6a44d Docs: change FE names to be more consistent
solidsanek added 2 commits 2023-04-26 13:42:08 +00:00
ci/woodpecker/pr/woodpecker Pipeline is pending Details
8e761f59d7 Docs: More formatting
ilja commented 2023-05-21 08:14:27 +00:00
Contributor
Copy Link

That sounds reasonable enough to me. I don't have a strong opinion on these kinds of styling, even though I'd have probably ended up capitalizing them all myself

Well, to be clear; That's how I generally would do it, but I also don't have strong opinions on it either. Feel free to do what you think is best here. I think the important thing is mostly consistency.

As for the styling guide, I'm not sure how and what would be in it. I
feel that it's probably not a bad idea to encourage the use of the
elements Mkdocs has, at the very least.

I'm thinking use of the Mkdocs elements, use of American spelling, how to capitalise software names, bullet and sub-bullet points, try to avoid too technical descriptions... Basically everything that came up here. But all of that is really a separate thing, so probably outside the scope of this MR. It was more an idea that came to me. Something to maybe think about, rather than something that needs to be done now.

I was just thinking of submitting this as a starter, but there's a lot more that can be done in this MR

Generally I think it's good practice to keep MR's small. It's easier to review, and it allows to get improvements in faster. You already did a lot of good work here, it would be nice if this could already be part of the docs. Extra changes can always be done in follow-up MR's imo.

> That sounds reasonable enough to me. I don't have a strong opinion on these kinds of styling, even though I'd have probably ended up capitalizing them all myself Well, to be clear; That's how I generally would do it, but I also don't have strong opinions on it either. Feel free to do what you think is best here. I think the important thing is mostly consistency. > As for the styling guide, I'm not sure how and what would be in it. I feel that it's probably not a bad idea to encourage the use of the elements Mkdocs has, at the very least. I'm thinking use of the Mkdocs elements, use of American spelling, how to capitalise software names, bullet and sub-bullet points, try to avoid too technical descriptions... Basically everything that came up here. But all of that is really a separate thing, so probably outside the scope of this MR. It was more an idea that came to me. Something to maybe think about, rather than something that needs to be done now. > I was just thinking of submitting this as a starter, but there's a lot more that can be done in this MR Generally I think it's good practice to keep MR's small. It's easier to review, and it allows to get improvements in faster. You already did a lot of good work here, it would be nice if this could already be part of the docs. Extra changes can always be done in follow-up MR's imo.
solidsanek commented 2023-06-06 20:08:26 +00:00
Author
First-time contributor
Copy Link

Good point. I might just stop here, and potentially follow-up another time

Good point. I might just stop here, and potentially follow-up another time
solidsanek changed title from WIP: Docs: Fix typos to Docs: Fix typos 2023-06-06 20:08:51 +00:00
solidsanek added 1 commit 2023-06-06 20:09:02 +00:00
ci/woodpecker/pr/woodpecker Pipeline is pending Details
77e5ae2494 Merge branch 'develop' into fix-docs-typo
floatingghost reviewed 2023-07-17 18:57:24 +00:00
floatingghost left a comment
Owner
Copy Link

heck this is a lot, most of it standardisation which is very appreicated

some tiny little grammatical things but apart from these i couldn't spot anything obvious to comment on

heck this is a lot, most of it standardisation which is very appreicated some tiny little grammatical things but apart from these i couldn't spot anything obvious to comment on
docs/docs/configuration/cheatsheet.md Outdated
@ -37,2 +36,3 @@
* `public`: Allows unauthenticated access to public resources on your instance. This is essentially used as the default value for `:restrict_unauthenticated`.
See `restrict_unauthenticated` for more details.
* `quarantined_instances`: *DEPRECATED* ActivityPub instances where activities will not be sent. They can still reach there via other means, we just won't send them.
* `quarantined_instances`: *DEPRECATED* ActivityPub instances where activities will not be sent. They can still reach there via other means; we just won't send them.
floatingghost commented 2023-07-17 18:52:50 +00:00
Owner
Copy Link

should probably be reach them

should probably be `reach them`
solidsanek marked this conversation as resolved
docs/docs/configuration/cheatsheet.md Outdated
@ -82,3 +81,2 @@
* `subject`: A subject of welcome email.
* `html`: A html that will be send to a newly registered users as a email.
* `text`: A text that will be send to a newly registered users as a email.
* `html`: A HTML that will be sent to a newly registered users as an email.
floatingghost commented 2023-07-17 18:53:11 +00:00
Owner
Copy Link

this should probably have the leading A stripped

this should probably have the leading `A` stripped
solidsanek marked this conversation as resolved
docs/docs/configuration/cheatsheet.md Outdated
@ -362,3 +361,3 @@
* `invalidation`: options for remove media from cache after delete object:
* `enabled`: Enables purge cache
* `provider`: Which one of the [purge cache strategy](#purge-cache-strategy) to use.
* `provider`: Which one of the [purge cache strategy](#purge-cache-strategy) to use.
floatingghost commented 2023-07-17 18:53:57 +00:00
Owner
Copy Link

should probably be pluralised to strategies

should probably be pluralised to strategies
solidsanek marked this conversation as resolved
docs/docs/configuration/cheatsheet.md Outdated
@ -377,3 +376,2 @@
This strategy allow perform external shell script to purge cache.
Urls of attachments are passed to the script as arguments.
This strategy allows to perform external shell script to purge cache.
floatingghost commented 2023-07-17 18:54:22 +00:00
Owner
Copy Link

allows performing an

`allows performing an`
solidsanek marked this conversation as resolved
floatingghost commented 2023-07-17 18:57:49 +00:00
Owner
Copy Link

oh and it looks like you might have to rebase, apologies

hope the diff isn't awful

oh and it looks like you might have to rebase, apologies hope the diff isn't awful
solidsanek added 1 commit 2023-08-05 10:01:28 +00:00
ci/woodpecker/pr/build-amd64 Pipeline is pending Details
ci/woodpecker/pr/build-arm64 Pipeline is pending Details
ci/woodpecker/pr/docs Pipeline is pending Details
ci/woodpecker/pr/test Pipeline is pending Details
5705569bc3 Merge remote-tracking branch 'upstream/develop' into fix-docs-typo
solidsanek added 1 commit 2023-08-05 10:32:14 +00:00
ci/woodpecker/pr/build-amd64 Pipeline is pending Details
ci/woodpecker/pr/build-arm64 Pipeline is pending Details
ci/woodpecker/pr/docs Pipeline is pending Details
ci/woodpecker/pr/test Pipeline is pending Details
5f9c28c8fa Docs: More formatting and typo correction
solidsanek commented 2023-08-05 10:33:22 +00:00
Author
First-time contributor
Copy Link

Should be good now, I think. At least as a first attempt to format and fix all this

Should be good now, I think. At least as a first attempt to format and fix all this
Oneric reviewed 2024-01-26 21:14:36 +00:00
docs/docs/administration/backup.md
@ -41,2 +41,2 @@
4. Remove the files and folders you created during installation (see installation guide). This includes the akkoma, nginx and systemd files and folders.
5. Reload nginx now that the configuration is removed `systemctl reload nginx`
4. Remove the files and folders you created during installation (see installation guide). This includes the Akkoma, NGINX and systemd files and folders.
5. Reload NGINX now that the configuration is removed `systemctl reload nginx`
Oneric commented 2024-01-26 21:14:36 +00:00
Member
Copy Link

(Also applies to all other nginx changes):

While nginx’ logo is styled after uppercase N and G letters, in textual form the software afaict consistently refers to itself as all-lowercase “nginx” even at the start of a sentence, see e.g. their docs from the repo or https://nginx.org/en/

The company (nginx.com) on the other hand is referred to as “Nginx, Inc.” on nginx.org, but appears to have referred to itself as all-capitla NGINX since early on while initially keeping to use lowercase nginx for the actual software. Today, the company appears to use all-capaital NGINX for both itself and indeed also the software.

This makes this somewhat ambiguous, but personally I am inclined to follow what’s used by the software itself and updating the odd occurences of Nginx to nginx instead of switching everything over to NGINX.

EDIT: a commit implementing this and another thing is linked above

(Also applies to all other nginx changes): While nginx’ logo is styled after uppercase `N` and `G` letters, in textual form the software afaict consistently refers to itself as all-lowercase “nginx” even at the start of a sentence, see e.g. their docs from the repo or https://nginx.org/en/ The company (nginx.com) on the other hand is referred to as “Nginx, Inc.” on nginx.org, but appears to have referred to itself as all-capitla NGINX since [early on](https://web.archive.org/web/20110902235354/https://www.nginx.com/) while initially keeping to use lowercase nginx for the actual software. Today, the company appears to use all-capaital NGINX for both itself and indeed also the software. This makes this somewhat ambiguous, but personally I am inclined to follow what’s used by the software itself and updating the odd occurences of `Nginx` to `nginx` instead of switching everything over to `NGINX`. **EDIT:** a commit implementing this and another thing is linked [above](https://akkoma.dev/AkkomaGang/akkoma/pulls/525#issuecomment-10503)
Some checks are pending
ci/woodpecker/pr/build-amd64 Pipeline is pending
Details
ci/woodpecker/pr/build-arm64 Pipeline is pending
Details
ci/woodpecker/pr/docs Pipeline is pending
Details
ci/woodpecker/pr/test Pipeline is pending
Details
This pull request has changes conflicting with the target branch.
  • SECURITY.md
  • docs/docs/administration/backup.md
  • docs/docs/administration/monitoring.md
  • docs/docs/configuration/cheatsheet.md
  • docs/docs/configuration/howto_mediaproxy.md
  • docs/docs/development/API/differences_in_mastoapi_responses.md
  • docs/docs/installation/alpine_linux_en.md
  • docs/docs/installation/arch_linux_en.md
  • docs/docs/installation/debian_based_en.md
  • docs/docs/installation/docker_en.md
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
approved, awaiting change

   
bug

Something is not working

  
configuration

This requires config changes

  
documentation

This is about human-readable docs

  
duplicate

This issue or pull request already exists

  
enhancement

New feature

  
extremely low priority

   
feature request

Something new?

  
Fix it yourself

Support has been attempted

  
help wanted

Need some help

  
invalid

Something is wrong

  
mastodon_api

   
needs docs

   
needs tests

   
not a bug

   
planned

   
pleroma_api

   
privacy

   
question

More information is needed

  
static_fe

   
triage

   
wontfix

This won't be fixed

No Label
approved, awaiting change
bug
configuration
documentation
duplicate
enhancement
extremely low priority
feature request
Fix it yourself
help wanted
invalid
mastodon_api
needs docs
needs tests
not a bug
planned
pleroma_api
privacy
question
static_fe
triage
wontfix
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
4 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: AkkomaGang/akkoma#525
No description provided.
Delete Branch "solidsanek/akkoma:fix-docs-typo"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?