Hello,

Please pardon a slightly off-topic comment, but I would like to highlight a part of Odhiambo's post. Heavily nested inline replies also reflect the issue I wish to comment on, so I'm not going to.

Granted, I am a slow learner, and perhaps already so mixed up after reading

the myriad HOWTOs for installing MM3 that are available online. I am tempted to say there are many like me who are likely to miss "where to obtain" other settings from.

and

Is it possible to modify the documentation to somehow make it obvious (in a language that a layman can easily understand,

I have seen this with several open source projects lately. There's no big picture, just 'hundreds' of cross-linked little bits of disjointed information that almost seem like documentation for individual modules.

I once joined a large commercial project for a major US computer company (sorry, I won't share details). They were quite proud of their extensive documentation. The docs for their equivalent of the kernel syscall interface, when printed (two-sided) and stacked, would easily approach 2 meters tall. Yet, every bit of it was incomprehensible unless and until you called the developer and had them explain it to you.

The problem that we all have, us humans, is that when we are very familiar with something, like the code we've been working on, it is very hard to describe its purpose to somebody who knows nothing about it. ("It's obvious to me, so it should be obvious to you.").

So, a challenge for us all: When writing and reviewing your documentation, imagine that you're explaining your whole project face-to-face to your grandmother, or to anybody who never learned to program. From experience I promise that it's easy once you get the hang of it.

Thank you and sorry for the speech.

-Dave

-- Dave Hall Binghamton University

On Sat, Jan 28, 2023 at 2:54 AM Odhiambo Washington <odhiambo@gmail.com> wrote:

On Fri, Jan 27, 2023 at 9:34 PM Mark Sapiro <mark@msapiro.net> wrote:

...

...

On Mon, Jan 23, 2023 at 11:48 PM Mark Sapiro <mark@msapiro.net> wrote:

...

Note that when following https://docs.mailman3.org/en/latest/install/virtualenv.html you

create

...

/etc/mailman3/settings.py and it contains

from mailman_web.settings.base import *
from mailman_web.settings.mailman import *

to establish a base set of settings that can be augmented or overridden in /etc/mailman3/settings.py. mailman_web.settings.mailman in turn contains

HAYSTACK_CONNECTIONS = {
      'default': {
          'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
          'PATH': "fulltext_index",

which is a relative path for fulltext_index and may need to be set to an absolute path.

Mi Mark,

I have read this page - https://docs.mailman3.org/en/latest/install/virtualenv.html and further

On 1/27/23 05:53, Odhiambo Washington wrote: -

...

https://docs.mailman3.org/en/latest/install/virtualenv.html#initial-config

...

...

• without clicking any external links. I still don't see the HAYSTACK_CONNECTIONS in the settings.py included on that page. I am missing something obvious, no?

Please reread what I wrote above. HAYSTACK_CONNECTIONS is not in the suggested settings.py but it is in mailman_web.settings.mailman and is imported by the suggested settings.py.

I have reread what you wrote now and I'm beginning to get the hang of this method. My observation is that it can only be _obvious_ to someone very familiar with Python config to decipher that *additional* settings *that can be augmented or overridden in /etc/mailman3/settings.py* can be obtained from: /PATH-TO/mailman_web/settings/{base|mailman}.py after they have noticed these two lines in the sample settings given in /etc/mailman3/settings.py:

from mailman_web.settings.base import *from mailman_web.settings.mailman import *

[At first instance, it is not obvious that mailman_web.settings.base and mailman_web.settings.mailman are actually paths in Python - which magically translates to mailman_web/settings/base.py and mailman_web/settings/mailman.py] Granted, I am a slow learner, and perhaps already so mixed up after reading the myriad HOWTOs for installing MM3 that are available online. I am tempted to say there are many like me who are likely to miss "where to obtain" other settings from.

For example, my mind all along has been tuned to having a settings_local.py

for overriding the settings.py. However, with this particular documentation, it would appear that everything is intended to just go into /etc/mailman3/settings.py.

Is it possible to modify the documentation to somehow make it obvious (in a language that a layman can easily understand, that those two "import *" _DO establish a base set of settings that can be augmented or overridden in /etc/mailman3/settings.py_ and that those settings are in what file(s) ?

I am not saying @Johannes Rohr <johannes@rohr.org> is a layman like me, but I think that is what hit him.

-- Best regards, Odhiambo WASHINGTON, Nairobi,KE +254 7 3200 0004/+254 7 2274 3223 "Oh, the cruft.", egrep -v '^$|^.*#' ¯\_(ツ)_/¯ :-)

---

Mailman-users mailing list -- mailman-users@mailman3.org To unsubscribe send an email to mailman-users-leave@mailman3.org https://lists.mailman3.org/mailman3/lists/mailman-users.mailman3.org/ Archived at: https://lists.mailman3.org/archives/list/mailman-users@mailman3.org/message/...

This message sent to kdhall@binghamton.edu