On keeping the docs

[Jelmer Vernooij]

Am Thursday, den 13.09.2012, 12:27 +0200 schrieb 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.
I've seen this tried for other projects before (Bazaar, Dovecot) that
originally just had documentation just on the wiki and eventually added
in-tree documentation again. 

Wikis are a great way to gather notes, and having a wiki is certainly
better than not having anything documented at all. Wikis are also fairly
unstructured, making it hard to find relevant information. If nobody is
actively editing a wiki - like our current documentation - then we end
up with incorrect information, which is probably worse. For example, the
init scripts on the wiki were pretty broken. 

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. The HOWTO collection has a lot more
information than is currently on the wiki.

Cheers,

Jelmer