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

[Michael Adam]

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?

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

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

Cheers - Michael
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 215 bytes
Desc: Digital signature
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140402/ff4445c2/attachment-0001.pgp>