-
-
Notifications
You must be signed in to change notification settings - Fork 2k
docs: Refactor pages for Account Management #4122
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Refactor pages for Account Management #4122
Conversation
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.
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?_)
|
Documentation preview for this PR is ready! π Built with commit: 72e7d75 |
georglauterbach
left a comment
There was a problem hiding this 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.
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.
Cheers! |






















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:
ACCOUNT_PROVISIONERdoc pages forFILEandLDAP:setupCLI support and config formats. The alias section covers some notable issues related to this provisioner.ACCOUNT_PROVISIONER=FILE, thus is hidden away under "Overview" page "Technical Details" for the quota section.LDAPdocs have intentionally not been revised in this PR, there's enough changes here already. That rewrite will follow.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.
Fixes #4117
Type of change
Checklist
docs/)CHANGELOG.md