Skip to content

docs: misc improvements (but mostly related to Rspamd)#3858

Merged
georglauterbach merged 8 commits intomasterfrom
docs/misc-improvements
Feb 2, 2024
Merged

docs: misc improvements (but mostly related to Rspamd)#3858
georglauterbach merged 8 commits intomasterfrom
docs/misc-improvements

Conversation

@georglauterbach
Copy link
Copy Markdown
Member

@georglauterbach georglauterbach commented Jan 30, 2024

Description

Various fixes to our Rspamd docs, CHANGELOG and PR template (wording). GitHub uses an advanced diff that makes the wording changes to the Rspamd docs page easier to review, which is nice.

Fixes #3857 but does even more

Just FYI: I have finally gotten around to bying LanguageTool Premium, which I used for my masters thesis too. Many wording changes were pointed out by this tool; for someone on the looks for such a tool, I can highly recommend it :)

Type of change

  • This change is a pure documentation update

@georglauterbach georglauterbach added kind/improvement Improve an existing feature, configuration file or the documentation area/documentation labels Jan 30, 2024
@georglauterbach georglauterbach added this to the v14.0.0 milestone Jan 30, 2024
@georglauterbach georglauterbach self-assigned this Jan 30, 2024
Copy link
Copy Markdown
Member

@polarathene polarathene left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

Some suggestions, mostly the ref link naming convention and DMS repo links (use tag instead of master branch)


Many wording changes were pointed out by this tool; for someone on the looks for such a tool, I can highly recommend it :)

Quite cool, reminds me of Grammarly :)

Comment thread docs/content/config/security/rspamd.md Outdated
Comment thread docs/content/config/security/rspamd.md Outdated
Comment thread docs/content/config/security/rspamd.md
Comment thread docs/content/config/security/rspamd.md Outdated
Comment thread docs/content/config/security/rspamd.md Outdated
Comment thread docs/content/config/security/rspamd.md Outdated
Comment on lines +245 to +258
[www::rspamd-homepage]: https://rspamd.com/
[www::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/blob/master/target/rspamd/local.d/actions.conf
[www::rspamd-docs-bayes]: https://rspamd.com/doc/configuration/statistic.html
[www::rspamd-docs-proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode
[www::rspamd-docs-web-interface]: https://rspamd.com/webui/
[www::rspamd-docs-modules]: https://rspamd.com/doc/modules/
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/?do=findComment&comment=119818

[www::rspamd-docs-override-dir]: https://www.rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[www::rspamd-docs-config-directories]: https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[www::rspamd-docs-basic-options]: https://rspamd.com/doc/configuration/options.html

[www::abusix]: https://abusix.com/
[www::abusix-rspamd-integration]: https://docs.abusix.com/abusix-mail-intelligence/gbG8EcJ3x3fSUv8cMZLiwA/getting-started/dmw9dcwSGSNQiLTssFAnBW#rspamd
Copy link
Copy Markdown
Member

@polarathene polarathene Jan 30, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very happy about moving all these down to here, much easier overview of links 👍

Generally the www style prefix isn't that useful.

  • Better to use the main topic such as rspamd or abusix. Your -docs suffix is good so we can use that before :: which we're using as a scope delimiter convention (or commonly as a boundary / separator to a group of related words).
  • Likewise for the actual webpage references, swapping -docs for -web works. Adapted abusix to the same convention.
  • For the DMS repo link, dms-repo is a bit more useful.
    • master branch isn't stable as a docs reference, so I've opted for the future v14.0.0 tag instead.
    • While that tag may get stale over time the user can easily change the tag or switch to master, if it breaks they can work their way back in tag or try find out where the new location is.
    • In future, I may get around to returning to a CI feature with lychee I was working on in 2022, that scans our docs for broken links as a lint (and scheduled job that opens an issue for the live latest docs). That'd allow an easy regex pattern to find & replace the tags across docs and verify all is good (well not exactly, if we referenced a portion of the file, it may no longer exist in that file).
  • rbl-vs-dnsbl I don't have input on. I typically just use that or prefix some category/group it's relevant to, no issue leaving that as-is or omitting the www::.
Suggested change
[www::rspamd-homepage]: https://rspamd.com/
[www::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/blob/master/target/rspamd/local.d/actions.conf
[www::rspamd-docs-bayes]: https://rspamd.com/doc/configuration/statistic.html
[www::rspamd-docs-proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode
[www::rspamd-docs-web-interface]: https://rspamd.com/webui/
[www::rspamd-docs-modules]: https://rspamd.com/doc/modules/
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/?do=findComment&comment=119818
[www::rspamd-docs-override-dir]: https://www.rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[www::rspamd-docs-config-directories]: https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[www::rspamd-docs-basic-options]: https://rspamd.com/doc/configuration/options.html
[www::abusix]: https://abusix.com/
[www::abusix-rspamd-integration]: https://docs.abusix.com/abusix-mail-intelligence/gbG8EcJ3x3fSUv8cMZLiwA/getting-started/dmw9dcwSGSNQiLTssFAnBW#rspamd
[rspamd-web]: https://rspamd.com/
[rspamd-docs::bayes]: https://rspamd.com/doc/configuration/statistic.html
[rspamd-docs::proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode
[rspamd-docs::web-interface]: https://rspamd.com/webui/
[rspamd-docs::modules]: https://rspamd.com/doc/modules/
[rspamd-docs::override-dir]: https://www.rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[rspamd-docs::config-directories]: https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
[rspamd-docs::basic-options]: https://rspamd.com/doc/configuration/options.html
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/?do=findComment&comment=119818
[abusix-web]: https://abusix.com/
[abusix-docs::rspamd-integration]: https://docs.abusix.com/abusix-mail-intelligence/gbG8EcJ3x3fSUv8cMZLiwA/getting-started/dmw9dcwSGSNQiLTssFAnBW#rspamd
[dms-repo::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/blob/v14.0.0/target/rspamd/local.d/actions.conf

Comment thread docs/content/config/security/rspamd.md Outdated
@georglauterbach
Copy link
Copy Markdown
Member Author

LGTM 👍

Some suggestions, mostly the ref link naming convention and DMS repo links (use tag instead of master branch)

👍🏼

Many wording changes were pointed out by this tool; for someone on the looks for such a tool, I can highly recommend it :)

Quite cool, reminds me of Grammarly :)

Yeah, but for less money and for more languages 🚀 It's funded by the EU directly as well, hence many languages in the EU are present.

casperklein
casperklein previously approved these changes Feb 1, 2024
polarathene
polarathene previously approved these changes Feb 1, 2024
@georglauterbach georglauterbach merged commit db661bf into master Feb 2, 2024
@georglauterbach georglauterbach deleted the docs/misc-improvements branch February 2, 2024 17:38
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Feb 2, 2024

Documentation preview for this PR is ready! 🎉

Built with commit: 0ae9145

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation kind/improvement Improve an existing feature, configuration file or the documentation

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

question: Default enabled services

3 participants