httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: [docs] mod_md documentation clarification
Date Wed, 06 Dec 2017 20:48:45 GMT


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 
> <mailto:stefan.eissing@greenbytes.de>>:
> 
> 
>     > Am 28.11.2017 um 16:40 schrieb Rich Bowen <rbowen@rcbowen.com <mailto:rbowen@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.



Mime
View raw message