You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by Rich Bowen <rb...@rcbowen.com> on 2017/11/28 15:40:47 UTC

[docs] mod_md documentation clarification

I'm reading the mod_md docs, and want some clarification on the 
following. In the docs for directive ManagedDomain, we have:

There are two special names that you may use in this directive: 'manual' 
and 'auto'. This determines if a Managed Domain shall have exactly the 
name list as is configured ('manual') or offer more convenience. With 
'auto' all names of a virtual host are added to a MD.

This is followed by an example that uses neither 'manual' nor 'auto', 
and thus it's unclear what the above paragraph refers to.

I believe that it refers to the MDDriveMode directive, which does not 
appear in the example.

I propose to patch the above paragraph to clarify that that's what's 
being talked about.

Related: I also would like to question the wisdom of having a 
ManagedDomain directive and a <ManagedDomain> container. This will most 
assuredly lead to user confusion and lengthy IRC conversations. I would 
request that the naming of one of these directives be reconsidered. (No, 
I'm not suggesting anything. I suck at naming things.)

Re: [docs] mod_md documentation clarification

Posted by Rich Bowen <rb...@rcbowen.com>.
On 11/28/2017 11:06 AM, Stefan Eissing wrote:
> 
> 
>> Am 28.11.2017 um 16:40 schrieb Rich Bowen <rb...@rcbowen.com>:
>>
>> I'm reading the mod_md docs, and want some clarification on the following. In the docs for directive ManagedDomain, we have:
> 
> Thanks for reviewing these.
> 
>> There are two special names that you may use in this directive: 'manual' and 'auto'. This determines if a Managed Domain shall have exactly the name list as is configured ('manual') or offer more convenience. With 'auto' all names of a virtual host are added to a MD.
>>
>> This is followed by an example that uses neither 'manual' nor 'auto', and thus it's unclear what the above paragraph refers to.
> 
> I updated the section with an additional example and more explanation.

Thanks. That's much clearer, and not the way I had interpreted it before.

Re: [docs] mod_md documentation clarification

Posted by Rich Bowen <rb...@rcbowen.com>.

On 12/02/2017 04:23 AM, Luca Toscano wrote:
> Hi Rich,
> 
> 2017-11-28 17:06 GMT+01:00 Stefan Eissing <stefan.eissing@greenbytes.de 
> <ma...@greenbytes.de>>:
> 
> 
>     > Am 28.11.2017 um 16:40 schrieb Rich Bowen <rbowen@rcbowen.com <ma...@rcbowen.com>>:
>     > Related: I also would like to question the wisdom of having a ManagedDomain directive and a <ManagedDomain> container. This will most assuredly lead to user confusion and lengthy IRC conversations. I would request that the naming of one of these directives be reconsidered. (No, I'm not suggesting anything. I suck at naming things.)
> 
>     I concur that you have more experience in supporting httpd users
>     than myself. Personally, I do like it obviously.
> 
> 
> I am really interested to follow up this topic, it seems really 
> important before moving mod_md to 2.4. What are the use cases that you 
> have in mind about users getting confused? The first one that comes up 
> in my mind is somebody looking for "ManagedDomain" on a search engine 
> and clicking on the <ManagedDomain> link, ending up thinking that only 
> that one exists. 

That is exactly the scenario that I had in mind.

And I can see how this might turn up to be a IRC
> nightmare, but maybe it could be resolved with good documentation? I 

It's certainly possible that we can resolve this with good 
documentation. However, there's always third-party "documentation" and 
forum advice.

> have in mind some changes to add warnings in both directives, stating 
> very clearly in each one that the other one also exists, but I am not 
> sure how well this solution could solve the issue.
> 
> The other risk that I can see having something like ManagedDomain and 
> <ManagedDomainDefine> (or whatever name we choose) is that users will 
> get confused while trying to figure out what are the differences between 
> the two, ending up in IRC again :D
> 
> I would also like to get feedback from other people involved in users 
> support on IRC if possible, this is the right moment to get some wisdom 
> from them.
> 
> Thanks a lot Rich for bringing up this subject!

Yeah, I don't feel so strongly about it that I'd want to force my 
opinion down anybody's throat. I know, too, that naming things 
"intuitively" is very, very hard.

Re: [docs] mod_md documentation clarification

Posted by Luca Toscano <to...@gmail.com>.
Hi Rich,

2017-11-28 17:06 GMT+01:00 Stefan Eissing <st...@greenbytes.de>:

>
> > Am 28.11.2017 um 16:40 schrieb Rich Bowen <rb...@rcbowen.com>:
> > Related: I also would like to question the wisdom of having a
> ManagedDomain directive and a <ManagedDomain> container. This will most
> assuredly lead to user confusion and lengthy IRC conversations. I would
> request that the naming of one of these directives be reconsidered. (No,
> I'm not suggesting anything. I suck at naming things.)
>
> I concur that you have more experience in supporting httpd users than
> myself. Personally, I do like it obviously.


I am really interested to follow up this topic, it seems really important
before moving mod_md to 2.4. What are the use cases that you have in mind
about users getting confused? The first one that comes up in my mind is
somebody looking for "ManagedDomain" on a search engine and clicking on the
<ManagedDomain> link, ending up thinking that only that one exists. And I
can see how this might turn up to be a IRC nightmare, but maybe it could be
resolved with good documentation? I have in mind some changes to add
warnings in both directives, stating very clearly in each one that the
other one also exists, but I am not sure how well this solution could solve
the issue.

The other risk that I can see having something like ManagedDomain and
<ManagedDomainDefine> (or whatever name we choose) is that users will get
confused while trying to figure out what are the differences between the
two, ending up in IRC again :D

I would also like to get feedback from other people involved in users
support on IRC if possible, this is the right moment to get some wisdom
from them.

Thanks a lot Rich for bringing up this subject!

Luca

Re: [docs] mod_md documentation clarification

Posted by Stefan Eissing <st...@greenbytes.de>.

> Am 28.11.2017 um 16:40 schrieb Rich Bowen <rb...@rcbowen.com>:
> 
> I'm reading the mod_md docs, and want some clarification on the following. In the docs for directive ManagedDomain, we have:

Thanks for reviewing these.

> There are two special names that you may use in this directive: 'manual' and 'auto'. This determines if a Managed Domain shall have exactly the name list as is configured ('manual') or offer more convenience. With 'auto' all names of a virtual host are added to a MD.
> 
> This is followed by an example that uses neither 'manual' nor 'auto', and thus it's unclear what the above paragraph refers to.

I updated the section with an additional example and more explanation.

> I believe that it refers to the MDDriveMode directive, which does not appear in the example.
> 
> I propose to patch the above paragraph to clarify that that's what's being talked about.
> 


> Related: I also would like to question the wisdom of having a ManagedDomain directive and a <ManagedDomain> container. This will most assuredly lead to user confusion and lengthy IRC conversations. I would request that the naming of one of these directives be reconsidered. (No, I'm not suggesting anything. I suck at naming things.)

I concur that you have more experience in supporting httpd users than myself. Personally, I do like it obviously. 

(I am biased and suck at renaming things.)

-Stefan