On keeping the docs

[Michael Adam]

On 2012-09-14 at 03:25 +0900, TAKAHASHI Motonobu wrote:
> From: Jelmer Vernooij <jelmer at samba.org>
> Date: Thu, 13 Sep 2012 14:12:41 +0200
> 
> > Am Thursday, den 13.09.2012, 13:28 +0200 schrieb Björn JACKE:
> > > On 2012-09-13 at 12:58 +0200 Jelmer Vernooij sent off:
> > > > I'm a big fan of wikis and I think they're a great tool, but wikis are
> > > > not magic - either way we'll need editors who keep an eye on the
> > > > contents and coherency of the docs.
> > > 
> > > for that reason I ѕaid we should all monitor wiki changes (there is that nice
> > > watch feature). Changes in the wiki should be looked at just like we
> > > look at the commit messages in git.
> > 
> > > > The HOWTO collection has a lot more
> > > > information than is currently on the wiki.
> > > 
> > > that's why I proposed to make selective c&p work from the howto collection to
> > > the wiki and still give a pointer to the old and partly outdated howto
> > > collection. And we have no timeslots for redundant documentation work, don't
> > > you agree?
> > 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.
> 
> Wiki tends to show informations only for the latest versions.
> 
> When someone has to use an older version for some reasons and wants to
> look at HowTos for the version, it's difficult to search on Wiki.
> 
> Outdated informations are useful for the people who have to use some
> outdated versions.

That is correct, but if the current master or the latest release
does not contain the outdated doceuments, it does not mean that
they are gone: They are still there on the website and in the
older release tarballs (even the old release branches).

On the other hand the outdated documents in the release tarball
have been a source of a lot of confusion, since the presence of
the docs makes people think that the contained information is
correct and up to date for the release that ships the docs.
(Which is not an insane assumption... ;-)

So it would be a good step imho to remove the legacy docs.
At the very least we should not compile the docs and ship
the compiled docs with the release. (We have done this in RC1.)

But it might even be worth considering to remove the legacy docs'
sources from the tree or at least clearly mark them deprecated
or outdated.

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/26871ff1/attachment.pgp>