On keeping the docs

[Björn JACKE]

On 2012-09-13 at 07:03 +1000 Andrew Bartlett sent off:
> Just to follow up on the thread about what to do about the howto
> collection.
> 
> Many of the docs (particularly the Samba HOWTO) are now a little out of
> date, and most have not had major revisions in years. 
> 
> However, while we tend to focus on how out of date they are, we forget
> how little Samba administration changes (or how much we value backwards
> comparability).  I did chat with Jelmer on this, who reminded me (but
> didn't get a chance to write to the list) that it is still much easier
> to fix up old docs than to start from scratch. 

I also discussed this with Karolin some days ago. We came to the point that,
yes, the howto collection is quite out of date and contains stuff that we would
not recommend. There is nobody who is actually taking care of that because
there is too little time for that for the people who did that in the past. We
have a hard time just getting the smb.conf options documented in the man page
actually.

In addition to that time moved on. >10 years ago, when the howto
collection was put together, wikis were not yet very popular. Today our wiki
contains some good stuff actually. IMHO we should concentrate on having ONE
good documentation and (imho) that should be the wiki. What we could all do to
improve that is monitor wiki changes so that we have an eye on it when someone
writes documentation with which we disagree with.

there are not enough timeslots to maintain a pdf style documentation parallel
to the wiki. We can c&p valid good stuff from the howto collection into the
wiki if we like to but we should drop the collection from upcoming releases and
point to the wiki for up-to-date documentation and just link to the howto
collection for the old, partly outdated documentation for now.

just my 2¢
Björn
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20120913/fffd8675/attachment.pgp>