On keeping the docs

[Michael Adam]

On 2012-09-14 at 12:10 +0200, Karolin Seeger wrote:
> 
> I like Andrew's proposal to let the docs in the git repo, but not to
> include them in the Samba release tarballs. Would you agree on this?

Yes, this is the absolute minimum we should do.
Shipping the outdated docs has caused so much confusion in the past.

I would even remove the sources or at least mark the docs as outdated.

> On Thu, Sep 13, 2012 at 02:12:41PM +0200, Jelmer Vernooij wrote:
> > Copying the documentation to the wiki and maintaining the wiki requires
> > time and effort too. I don't see why we would have manpower for that and
> > not for updating the existing documentation; I think the latter would
> > actually require less effort.

I don't think so.

For instance the samba3 howto is exactly a samba-THREE howto, for rather old
versions of samba3.

I think it would require a whole new howto for samba 4.0, not
merely some polishing and renaming of the samba3-howto.

And there are two arguments that indicate to me that the wiki
would require less effort:

* It is technically more difficult to edit the xml sources than
  it is to edit the wiki contents.

* The hurdle for contributions is less in the wiki. We do have a
  lot of Wiki contributors that are not team members, and they
  have contributed a lot of good stuff in the recent past. On the
  other hand maybe due to the more formal nature of commiting
  patches to the code repository, I am not aware of substantial
  recent external contributions to the howto and other docs.

That being said, I think that it would be desirable to have
up to date documentation like the howto and by-example docs
in the reop. But I don't think that we will have it in a
reasonable timeframe. And we do have vaguely up to date wiki docs.
(And again I don't think that we should ship legacy docs in the
hope that they will be updated sometime in the future.)

Just my 2¢...

Cheers - Michael

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 206 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20120914/cf94e2a5/attachment.pgp>