Hi Steve,

To be honest, I have not had many problems with the 2.4 documentation myself, having recently upgraded from 2.3 to 2.4. While I will admit that the upgrade guide is a bit rough, the only real impracticality I have found is that the 2.3 documentation seems to have been taken down, leading to 404s more often than not when searching for topics still relevant in 2.4.

Perhaps you could share some concrete examples as to how the 2.4 documentation is lacking?

Steve Litt via dovecot schreef op 2025-07-12 14:45:

Are you planning to improve your Dovecot 2.4.x documentation? The current 2.4.x documentation has:

• Non-obvious links between 2.4.x and 2.3.x
• Some 2.3.x specific grammar
• Almost no examples
• 2.4.x material is scattered across many pages
• Contains a few inaccuracies
• Contains some contradictions

2.4.x is such a huge change that it should have its own, standalone documentation tree exclusively for 2.4.x. This tree should have a different color scheme than your other docs so people know at a glance exactly what they're looking at.

You could have a page devoted to often used dovecot.conf content, with numerous examples, documented as if there had never been an earlier version. You could have a page devoted to conversion of 2.3.x dovecot.conf to 2.4.x, once again, with numerous examples. Another page with more exotic dovecot.conf content, with numerous examples. Another page discussing the 2.3.x features that don't appear in 2.4.x, what capabilities that takes away, and how best to cobble together those capabilities for those who don't want Dovecot Professional. Another page for brand new capabilities of 2.4.x.

Thanks,

SteveT

Steve Litt http://444domains.com

---

dovecot mailing list -- dovecot@dovecot.org To unsubscribe send an email to dovecot-leave@dovecot.org

Met vriendelijke groeten,

William David Edwards

On 12. Jul 2025, at 15.45, Steve Litt via dovecot <dovecot@dovecot.org> wrote:

Are you planning to improve your Dovecot 2.4.x documentation? The current 2.4.x documentation has:

• Non-obvious links between 2.4.x and 2.3.x

Not sure what you mean by this. v2.4 documentation should link only to v2.4 documentation pages. If there are links to v2.3 docs or v2.3 content (outside upgrading pages) it's likely a bug.

• Some 2.3.x specific grammar
• Contains a few inaccuracies
• Contains some contradictions

Specifics about these would be useful. I always fix mistakes in documentation when I find them. Larger issues take more time though..

• Almost no examples

v2.3 documentation was converted to v2.4, so about the same examples are there. Of course, more would be helpful. But suggestions for where to put examples specifically would help to know the pain points.

• 2.4.x material is scattered across many pages

Not sure what you mean by this.

2.4.x is such a huge change that it should have its own, standalone documentation tree exclusively for 2.4.x.

It should already be.

This tree should have a different color scheme than your other docs so people know at a glance exactly what they're looking at.

v1.x and v2.x documentation used to have this. Yeah, maybe we could have some coloring difference in them.

You could have a page devoted to often used dovecot.conf content, with numerous examples, documented as if there had never been an earlier version.

We have https://doc.dovecot.org/2.4.1/core/config/quick.html for getting a minimal Dovecot configuration running. It could perhaps be linking to pages of commonly used features, but I'd rather avoid duplicating much of the content.

On 12. Jul 2025, at 15.45, Steve Litt via dovecot <dovecot@dovecot.org> wrote:

 Are you planning to improve your Dovecot 2.4.x documentation? The
 current 2.4.x documentation has:

 * Non-obvious links between 2.4.x and 2.3.x

Not sure what you mean by this. v2.4 documentation should link only to v2.4 documentation pages. If there are links to v2.3 docs or v2.3 content (outside upgrading pages) it's likely a bug.

 * Some 2.3.x specific grammar
 * Contains a few inaccuracies
 * Contains some contradictions

Specifics about these would be useful. I always fix mistakes in documentation when I find them. Larger issues take more time though..

 * Almost no examples

v2.3 documentation was converted to v2.4, so about the same examples are there. Of course, more would be helpful. But suggestions for where to put examples specifically would help to know the pain points.

 * 2.4.x material is scattered across many pages

Not sure what you mean by this.

 2.4.x is such a huge change that it should have its own, standalone
 documentation tree exclusively for 2.4.x.

It should already be.

 This tree should have a
 different color scheme than your other docs so people know at a glance
 exactly what they're looking at.

v1.x and v2.x documentation used to have this. Yeah, maybe we could have some coloring difference in them.

 You could have a page devoted to often used dovecot.conf content,
 with numerous examples, documented as if there had never been an
 earlier version.

We have [1]https://doc.dovecot.org/2.4.1/core/config/quick.html for getting a minimal Dovecot configuration running. It could perhaps be linking to pages of commonly used features, but I'd rather avoid duplicating much of the content.

References

Visible links

1. https://doc.dovecot.org/2.4.1/core/config/quick.html