[Bf-docboard] wiki?

[Kent Mein]

In reply to Bart Veldhuizen (bart at vrotvrot.com):

> Hi Kent,
> 
> Op 1-jun-2005, om 18:26 heeft Kent Mein het volgende geschreven:
> 
> >Were using docuwiki internally here at work:
> >http://wiki.splitbrain.org/wiki:dokuwiki
> 
> having experience with a wiki, would you say that it is a suitable  
> medium for writing a book-like document such as the Blender manual  
> in? How would you say that the well-structured, (in my opinion)  
> harder to learn DocBook compares to a free-form, easy to learn Wiki  
> system?

I would say that there are tradeoffs to both.  With lower level systems
like DocBook/LaTeX and those sorts of things you probably get a nicer 
looking finished product but initial setup/learning is steeper for users.
DocBook the burden is on "writers"(People submitting content).
Where wiki burden is on "publishers"(People producing the Printed Book).

Problems I see with the current setup:
	Hard to get started.
	There is sometimes a lag with updates getting committed.  

	We basically in my mind have two products: online documentation
		and the printed manual, currently I think the online
		documentation seems to always be out of date and thats
		a pain for people wanting to work on the documentation
		(minor but still there) and for people just wanting to
		lookup something.  On the other hand fixing this issue
		would maybe make the published book less worth the money
		I personally think this is an issue that should be fixed
		though.

A wiki would address all of these issues but would introduce some new ones.
The biggest of which I would say is making the finished product (a printable
manual) would be more work probably to make it look good.
Another issue would be revision control would be more open, which I personally
don't think is a problem.  I don't think we would have bunches of 
misinformation committed if we were to open things up a little more.
Initial setup of the wiki might be complicated to get looking acceptable.

If we can get the printed book looking good with a wiki, 
I think the wiki would make life a lot easier for 99-97% of the 
documenting group which is a good thing.  I would say we can but
might make people doing the job a little harder.

I don't think a wiki is the only way to address issues stated above,
and don't really care how we fix them just issues I see with the current
setup.

Kent
-- 
mein at cs.umn.edu
http://www.cs.umn.edu/~mein