[Bug 219421] [patch] handbook jail chapter removing ezjail section

[Ernie Luzar]

Trev wrote:
> bugzilla-noreply at freebsd.org wrote on 21/05/2017 03:57:
>>             Bug ID: 219421
>>            Summary: [patch] handbook jail chapter removing ezjail 
>> >            Product: Documentation
>>            Version: Latest
>>           Hardware: Any
>>                 OS: Any
>>             Status: New
>>           Keywords: patch
>>           Severity: Affects Many People
>>           Priority: ---
>>          Component: Documentation
>>           Assignee: freebsd-doc at FreeBSD.org
>>           Reporter: qjail1 at a1poweruser.com
>>           Keywords: patch
>>
>> Created attachment 182757
>>   --> 
>> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=182757&action=edit
>> handbook jail chapter diff file
>>
>> In the comments for PR # 218849 people voiced concerns that it is
>> inappropriate for the handbook to devote a section on how to use a
>> port. That information belongs in the ports own documentation.
> 
> I had assumed that this was correct... the Handbook only dealt with 
> "base" and a ports section had inadvertently been included. Until today, 
> when I was looking at the mail section of the Handbook and came across 
> these sections devoted to "ports":
> 
> https://www.freebsd.org/doc/handbook/SMTP-Auth.html
> https://www.freebsd.org/doc/handbook/mail-agents.html
> https://www.freebsd.org/doc/handbook/mail-fetchmail.html
> https://www.freebsd.org/doc/handbook/mail-procmail.html
> 
> So, are all these sections to be removed also? Somehow I don't think so.
> 

After review, I see these handbook links are totally different than the 
detailed step by step how-to ezjail section of the handbook. They are 
night and day different.

It's not a question of providing names of ports that service a certain 
function. It's providing a whole section devoted to such in depth step 
by step instructions about a port. This gives the reader a implied 
endorsement of said port and the idea its the only solution. This is 
un-fair treatment of the other ports available as solutions for that 
same function. And more to the point this is the type of information 
that the port documentation it self should contain. When has it become 
the doc teams job to maintain a ports documentation? This is just so 
wrong on so many levels.

I don't remember there being any open discussion about adding this type 
of section detailing ezjail usage before it was added to the handbook.
It just showed up one day. I was not aware this is how major concept 
changes are made to the handbook. If the formal review process was done 
then please point me to it so I can understand the thinking back then 
that supported this.