Re: [docs] mod_md documentation clarification

[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

[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.