Brian Carpenter writes:
Thank you for going to the trouble of making your guide easily available to and usable by the community.
On 2/25/21 8:28 PM, Abhilash Raj wrote:
Is there a specific reason that you chose to go with an entirely new doc
Yes. Just from observing the communications on this list, there are multiple ways to install Mailman 3
Yes, and we try to document them all, written by different people at different times. I don't think that's an unreasonable approach given the wide variety of situations of our site admins, but I'm sure a lot of "greenfield" installations will appreciate your thorough, "from parts manifest to assembled working system", approach.
My guide represents a very stable and easily maintained environment for me and hopefully others.
I'm pretty sure that there are quite a few folks with very similar installations.
Is there an official guide? See that is the problem.
Yes, it has been a problem. At this point I'm pretty sure :^รพ that mailman.readthedocs.io is the official guide, but that hasn't been well-known in the past and there are a lot of mirrors and unofficial guides like yours (but not as thorough). And there's a lot of stuff on the Wiki that requires effort to integrate because it was originally written in reply to a particular user's questions.
I did not know there was an official guide. Because every time I tried finding documentation in the past using Google searches, I got fed outdated information. So for me the guide that I came up with, works great for me and if no one else uses it, I certainly will.
Is it something about the contribution process to the official documentation that makes it hard
Well I don't know much about any of the above approach to documentation. So I would say that is a hindrance.
Sphinx is pretty much the gold standard for Python documentation. It looks nice. The markup is reStructuredText, which is a powerful, Markup-like language with a few features that Markup didn't have last I looked, and it's extensible by Python programmers. It's also used in marking up Python docstrings. So you can see why we'd choose it. But if you're *not* an experienced Python programmer, none of those are advantages.
I am just trying to understand how can we lower the barrier for community members to help contribute to existing docs instead of them having to create new ones. Specifically around installation, since that tends to get stale often when depedent packages change or a new dependency is added that breaks the installation.
@Abhilash: For non-Python programmers, it's not *that* hard, but there is a hurdle at the beginning.
I think the best thing to do is to advertise that we're always looking for doc contributions, and that if somebody's not familiar with reST, they shouldn't let that stop them. Of course we'll help them with markup, and if necessary we'll do it.
The Dart Sass section came from Mark's comments on this list.
Now, automatic conversion of Mark's posts to reST documentation is a problem I wish we could get those Red Army AI programmers to work on!
Steve