Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Conversation

@polarathene
Copy link
Member

@polarathene polarathene commented Jul 19, 2024

Description

A bit overkill perhaps and a little rough in some areas πŸ˜…

I have been working on this rewrite on/off for a while. It groups the related pages under "Account Management", where we now have:

  • An overview page:
    • Mostly a technical reference, but I've been thorough documenting the sections in relation to DMS.
    • It's effectively a more polished document of notes I've littered around my comments in issues / discussions. It is intended to ease discovery / awareness of common misconceptions or caveats for users.
    • The sub-addressing section is especially improved from what our docs previously covered. The associated section in the Sieve page has seen a refactoring.
  • ACCOUNT_PROVISIONER doc pages for FILE and LDAP:
    • The current v14 "User Management" page was split across the new "Overview" and "File Based" pages.
    • The "File Based" page now better documents setup CLI support and config formats. The alias section covers some notable issues related to this provisioner.
    • Quota workaround isn't too user facing and is not specific to ACCOUNT_PROVISIONER=FILE, thus is hidden away under "Overview" page "Technical Details" for the quota section.
    • LDAP docs have intentionally not been revised in this PR, there's enough changes here already. That rewrite will follow.
  • Supplementary auth pages:
    • Both Dovecot Master Accounts and OAuth2 pages have been rewritten for better documentation for users and to benefit maintainers.

The intention with improving the quality of docs is that it may help attract more contributors, or minimize repeating myself a bit when users open issues/discussions and I need to hunt down and piece that information together πŸ˜“

The Overview page better covers the same concepts between the two provisioners, which I had found myself defining in the LDAP docs rewrite. I figured it was better to tackle this restructuring so that the LDAP docs can be more focused on LDAP specific concepts/config.


  • Git commit history is a bit erratic. I couldn't justify time to clean that up and I'm probably the only one who'd really be bothered by it anyway πŸ˜†
  • I'll provide before/after page links once the preview is deployed if that helps glance over (or just trust my work 😎 )
  • I want to have the LDAP section rewritten similarly for v14.1 before adapting to v15 breaking change rewrite. Extra effort on my part, but will smooth the process over for existing LDAP users which should equate to less support tickets πŸ™

Fixes #4117

Type of change

  • Improvement (non-breaking change that does improve existing functionality)

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation (README.md or the documentation under docs/)
  • New and existing unit tests pass locally with my changes
  • I have added information about changes made in this PR to CHANGELOG.md

Updates remaining links to account sections on this page instead (_for `accounts`, `aliases`, `quotas`_).

This page will cover the features and defer to separate pages for more specific content where relevant.
- Manual method not necessary to document.
- Condense `setup` example guidance.
- Quotas / Aliases content migrated to Overview when not specific about file provisioner.

Some of the content is this commit is not a complete revision.
Much better docs on the sub-addressing feature supported by Postfix and Dovecot, along with the guidance with usage in Sieve.
Add some context regarding DMS accounts and their distinction/overlap from the email address functionality, and it's relevant context for receiving/sending.

File provisioner, minor revisions to referencing associated config files and account management.
Better documented with links and coverage over the workaround details we've implemented.
Minor revisions with phrasing, admonitions for structure and better explanation of the feature functionality/purpose.
Extensively covers known issues and technical details that have been discussed often enough.

The improvements should benefit both users and maintainers.
This rewrite should more clearly document the feature, along with a better example and additional links for reference.
Minor update to this page:
- Links extracted to bottom of page as per convention.
- ENV file example converted to preferred `compose.yaml` ENV settings.
- Correct link to subaddressing section
- Make the config file example snippets intended filename less ambiguous.
- Minor rephrasng.
Revised the account section and added additional clarity for common confusion with relation to sender address and multi-domain support.

Top of the page now clarifies it's a technical reference and directs users to the related pages for configuration / caveats.

Technical Overview links to Dovecot docs were missing.
File based provisioner docs:
- Sections indent with info admonitions.
- Accounts section expanded with config format and example.
- Quotas section expanded and shifted to bottom (alphabetical sort).
- Split into `setup` CLI and config reference groups.

Overview page:
- Sections indent with info admonitions.
- Revised content.
This is related to accounts and aliases, but not provisioners, thus extract out of the accounts parent section.
This lacked documentation but was community contributed feature to allow further customization of a Dovecot Account.

It has caveats as DMS does not take these into consideration anywhere in scripts. Documenting officially for better awareness.
Better outline the OAuth2 login process, the two supported login mechanisms and their docs/rfcs, along with documenting caveat with mail client compatibility.

Add a verification tip for the OAuth2 support, showing how `curl` can be used, along with caveat presently affecting the `curl` in DMS v14.

Additionally note the feature still isn't documented fully, providing the user with additional references for more information.

`ACCOUNT_PROVISIONER` ENV docs minimized. No `OIDC` provisioner plans, the OAuth2 docs page now mentions SCIM 2.0 API as the next step towards resolving that concern. The tip admonition was removed as it no longer provides value, instead we link to the Account Management overview page.

Dovecot Master Accounts docs page now lightly document the `setup` CLI and config format for the feature.
@polarathene polarathene added kind/improvement Improve an existing feature, configuration file or the documentation area/documentation labels Jul 19, 2024
@polarathene polarathene added this to the v14.1.0 milestone Jul 19, 2024
@polarathene polarathene self-assigned this Jul 19, 2024
Some anchor links to different parts of our docs have gone stale. This branch also broke a few itself that I missed.

The build now only reports issues with anchor links to Content Tabs, which it must not be aware of during the build (_MKDocs Material specific feature?_)
@polarathene
Copy link
Member Author

polarathene commented Jul 19, 2024

Before / After comparisons (with page links)

If you rather just compare between current and preview docs, these two links will get you started:


New nav sidebar group hierarchy:

image


Before / After comparisons

ENV docs

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/environment/#account_provisioner

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/environment/#account_provisioner

image


Overview + File based

BEFORE: https://docker-mailserver.github.io/docker-mailserver/v14.0/config/user-management/

AFTER:

Accounts

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/user-management/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/overview/

image

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/provisioner/file/

image

image

Aliases

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/user-management/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/overview/

image

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/provisioner/file/

image

Quotas

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/user-management/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/overview/

image

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/provisioner/file/

image


Sub-addressing

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/user-management/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/overview/

image

Sieve - Subaddressing

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/advanced/mail-sieve/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/advanced/mail-sieve/

image

Dovecot Master Accounts

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/advanced/dovecot-master-accounts/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/supplementary/master-accounts/

image

image

OAuth2

Click to view

BEFORE

https://docker-mailserver.github.io/docker-mailserver/v14.0/config/advanced/auth-oauth2/

image

AFTER

https://pullrequest-4122--dms-doc-previews.netlify.app/config/account-management/supplementary/oauth2/

image

casperklein
casperklein previously approved these changes Jul 20, 2024
@github-actions
Copy link
Contributor

Documentation preview for this PR is ready! πŸŽ‰

Built with commit: 72e7d75

Copy link
Member

@georglauterbach georglauterbach left a comment

Choose a reason for hiding this comment

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

The new changes are definitely an improvement over the current state. I do not like the admonition-ception, though. Some of the text is IMO better as plain text. The new page has zero free text, which looks odd to me.

That being said, the changes are still an improvement. I have zero objections to merging it.

@polarathene
Copy link
Member Author

The new changes are definitely an improvement over the current state. I do not like the admonition-ception, though. Some of the text is IMO better as plain text. The new page has zero free text, which looks odd to me.

Earlier iterations had more admonition-free text. I have expressed in the past that I found the typography of the docs theme to be a bit bad. The distinction between sections and flow was quite muddy. I then went the route of using admonitions more heavily (and consistently in structure/pattern), which seemed to make it a bit more easier to grok where information was laid out.

If someone wants to take a shot afterwards and reduce the admonitions that is fine, but given some sections have quite a lot of text the admonitions more clearly separate the context they're associated to, and collapsed admonitions follow a UX principle of progressive disclosure, which is better than walls of text (or the opposite of too little text when you need that extra information).

Barely anyone contributes much to the docs (if they do it's usually a collab with me), so it's definitely a style that's spreading through our docs πŸ˜…

That said, I get it's not perfect but I don't have time to mess around with that. This is good enough IMO.


That being said, the changes are still an improvement. I have zero objections to merging it.

Cheers!

@polarathene polarathene merged commit 0698ad9 into docker-mailserver:master Jul 21, 2024
@georglauterbach georglauterbach modified the milestones: v14.1.0, v15.0.0 Sep 26, 2024
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

None yet

Development

Successfully merging this pull request may close these issues.

docs: ACCOUNT_PROVISIONER=FILE additional Dovecot user attribtues

3 participants