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.xNot 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 contradictionsSpecifics about these would be useful. I always fix mistakes in documentation when I find them. Larger issues take more time though..
* Almost no examplesv2.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 pagesNot 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