[PATCH 2/2] doc: remove outdate Samba3-HOWTO

Sun Apr 6 03:44:49 MDT 2014

On Wed, 2014-04-02 at 14:52 +0200, Michael Adam wrote:
> Hi Andrew and Björn,
> 
> exactly two months ago this question was raised
> and nothing happened since.
> 
> Hence I would like to pick it up again and argue to
> remove the docs in the simple fashion that Björn
> has proposed:
> 
> On 2014-02-02 at 09:31 +1300, Andrew Bartlett wrote:
> > On Fri, 2014-01-31 at 23:20 +0100, Björn Jacke wrote:
> > > our users expect the documentation to be correct but this one is
> > > completely
> > > outdated and it is less than helpful for people who look for help for
> > > recent
> > > samba versions as we can see on the samba mailing list recently.
> > 
> > Two years ago, I argued against this, I said the documentation could be
> > saved, and even started going over the docs, correcting the really bad
> > bugs and removing references to long-gone features. 
> > 
> > I would still prefer to see this as multiple commits, justifying why
> > each chapter is better removed than kept.  If that means we save some
> > small parts of the doc, then great, and if it means we have recorded
> > well why these bits of the documentation have simply fallen too far
> > behind, then even better.
> 
> I am not certain that there are really benefits this approach:
> - One commit to remove outdated documentation is a clear sign.
> - Explaining with more patches that each chapter is outdated
>   does not have any benefit other than bumping the author's
>   commit count, imho.
> - If we detect that we can save a chapter here and there, would
>   the resulting doc fragment still be worth being called
>   "Samba howto collection" or "samba by example book"?...
>   And who dies the work?

The reason I asked for that, is that I don't think it's a chapter here
or there that is still good and current.  Surprising as it seems, most
of what I've read tonight still looks reasonable, because we work hard
to keep our old configurations working.   I already removed all the 'we
are not an AD DC' stuff at the Samba 4.0 release time, and below I
remove a chapter on Kerberos that was showing its age. 

> > That said, the better of the two documents is the ByExample book, and it
> > essentially hasn't been touched in years, while the HOWTO has been
> > maintained more recently, but only because it's content is so old that
> > it is easy to remove the clearly erroneous stuff. 
> > 
> > The work I've done with Garming has certainly highlighted quite how much
> > can be plainly wrong in a document that we attempt to actively maintain,
> > and I therefore suspect but can't prove without examination that there
> > is now much wrong, often subtly, in the HOWTO and ByExample books. 
> > 
> > It is also clear that for those in our contributor base with time and
> > energy for documentation, that the wiki is the mechanism of choice.
> 
> Absolutely.
> 
> So this strongly argues in favour of removing the complete
> mentioned documents.

I think it argues for a proper examination.  I've tried to do some of
that tonight. 

> > Finally, the other reason for multiple commits is just a small list
> > etiquette I would ask:  This massive inline patch is enough to lock up
> > my Evolution for a noticeable time while it tries to render it, could
> > you please use an attachment for such a large patch in the future, or
> > split it into multiple mails, or post the diffstat and a link to a git
> > tree?
> 
> Of course such big mails may have a bad impact on inferior mail
> clients... ;-)
> 
> But while I prefer patches as attachments and git links anyways,
> I don't think this is a valid reason to request splitting up the
> patch.
> 
> Summing up, since I do not have ressources to do the complete
> review to find the odd chapter worth saving, and apparently
> no-one else had, either, I propose that we push Björns big
> removal patches.
> 
> If nobody opposes, I'll do so in a couple of days (start of next
> week, say).

I would still like us to take this a little more slowly, and to do this
in conjunction with Marc's documentation team efforts.  

Attached are four patches in that direction, one to correct a GPLv2/3
error, another to remove references to SWAT, another to remove most of
the confusing Samba-3 references, and a patch to remove references to
multiple passdb backends being active at once and finally a patch to do
as I suggested, to remove a chapter that is showing it's age.

(The removed chapter is amusing in that it claimed that the Samba Team
had a great track record for on-time releases, and so Samba4 would be
released in 2004 or 2005 ;-)

Please review/push. 

Andrew Bartlett

-- 
Andrew Bartlett                       http://samba.org/~abartlet/
Authentication Developer, Samba Team  http://samba.org
Samba Developer, Catalyst IT          http://catalyst.net.nz/services/samba

-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-docs-Remove-references-to-SWAT-now-removed.patch
Type: text/x-patch
Size: 24583 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140406/a32f6533/attachment-0005.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-docs-Samba-is-now-GPLv3.patch
Type: text/x-patch
Size: 987 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140406/a32f6533/attachment-0006.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0003-docs-Remove-most-references-to-Samba-3-and-change-to.patch
Type: text/x-patch
Size: 165408 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140406/a32f6533/attachment-0007.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0004-docs-Multiple-passdb-backend-support-has-been-remove.patch
Type: text/x-patch
Size: 5448 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140406/a32f6533/attachment-0008.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0005-docs-Remove-out-of-date-Kerberos-and-security-chapte.patch
Type: text/x-patch
Size: 85036 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140406/a32f6533/attachment-0009.bin>