docs: misc improvements (but mostly related to Rspamd)#3858
docs: misc improvements (but mostly related to Rspamd)#3858georglauterbach merged 8 commits intomasterfrom
Conversation
There was a problem hiding this comment.
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 :)
| [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 |
There was a problem hiding this comment.
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
rspamdorabusix. Your-docssuffix 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
-docsfor-webworks. Adaptedabusixto the same convention. - For the DMS repo link,
dms-repois a bit more useful.masterbranch isn't stable as a docs reference, so I've opted for the futurev14.0.0tag 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
latestdocs). 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-dnsblI 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 thewww::.
| [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 |
Co-authored-by: Brennan Kinney <[email protected]>
👍🏼
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. |
0ae9145
|
Documentation preview for this PR is ready! 🎉 Built with commit: 0ae9145 |
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