[dokuwiki] Re: Developers Manual and Documentation (where two mails)
- From: "Andreas Gohr" <andi@xxxxxxxxxxxxxx>
- To: "DokuWiki Mailinglist" <dokuwiki@xxxxxxxxxxxxx>
- Date: Tue, 7 Oct 2008 21:16:10 +0200
[Warning: this is gonna be long. There's a very short summary at the
end, so scroll down if you're short on time.]
Hey,
there where two threads started which both somehow touch DokuWiki's
documentation. This seems to be a point of much interest currently and
a lot of people seem to miss a bit here... Instead of answering both
threads individually I like to combine them in this mail.
Let's start with my opinion about a DokuWiki book.
First of all: When somebody wants to write a book the he should do
that. In that case it would be his (or her) book and personally I
don't care about the license then. Writing a book is a tremendous
amount of work (otherwise I would have written one myself already), if
the author wants to make as much money as possible from that I'm fine
with that.
What I *hate* are open source projects that are incomprehensible
without buying a book, training or similar stuff. I tried to work with
JBoss once and it was hell (dunno if that's still the case). But this
is clearly not the case with DokuWiki - all documentation is available
at dokuwiki.org. Whil's (or someone else's book) will not add anything
new to the documentation that is already available for free.
There is still sense in having a DokuWiki book (or even many DokuWiki books):
- it raises the awareness and credibility of DokuWiki - yes it's sad
but having a dead tree book on the shelves does that.
- some people prefer reading books over reading stuff on the screen
- a book can view DokuWiki from a certain perspective or focus on a
certain user level (Whil's book focuses on DokuWiki for software
developers) while the official documentation tries to satisfy everyone
- a book written by a single (outside) author might be more
streamlined than the docs written by many different inside and outside
contributors.
So should we do a collaborative book using a wiki? I say no. My
strongest objection is that we would suddenly have to maintain two
wikis about DokuWiki - the book wiki and dokuwiki.org.
We would also have to decide how to publish, because an unpublished
book is just a website. Then, when we publish, who would benefit from
the sales? I could probably go on with finding similar problems around
writing a collaborative book. I don't say it couldn't work, but I say
it's not worth the effort and would probably hurt the "real"
documentation more than a book would help.
So to answer Stefan's question:
> Should I just go ahead and put what I have in a wiki, so we (or better:
> new contributors) can hack on it together?
Please don't. Instead either keep it to you and finish this book on
your own (you can ask for help with proofreading and pointing out
errors like Whil did of course) or try to add everything you think is
missing to the dokuwiki.org Wiki.
Seriously I really think we did a very well job on the content
reorganization weekend already. We shouldn't stop here. The goal
should not be to trying to reinvent the wheel by writing a book but by
improving and extending the existing documentation.
Improving the documentation now finally brings me to the second
thread. Sebastian made some suggestions at
http://www.dokuwiki.org/devel:manual about improving the developers
docs. His suggestions look very much like a book outline to me ;-)
Sebastian, first: I like most of your suggestions but because it's
easier and fits with what I want to say in general, I do some
nitpicking here ;-)
I don't like the idea of a navigation with "next" and "previous"
links. I think it limits what a wiki is good at: creating hypertexts
with heavily interlinked content.
Next and previous links make no sense where information is more or
less equal important. Nobody will read the development section in one
go from start to end. Instead people always look for the info they
need right now.
BTW. I think this is mostly true for (non-fiction) books as well. At
least I never read a software book from start to end. Next and
previous links also make it very hard to introduce a page "between"
two other pages or to "reorder" the pages.
What I want to say with this is, that we should not try to emulate a
book with the wiki. Because we have a different and in many ways
better medium than a book. We should make use of the possibilities it
offers.
I suggest to use many intext-links instead of a fixed next/previous
navigation and a "See also" section at the end of every page. This
section then should contain links to related topics. I'd also like to
see this concept used much more in the whole documentation.
I most certainly agree that the pages in the devel namespace need some
serious clean up. Especially the plugin pages are a real mess right
now.
Adding simple and easy to understand examples to all devel pages is a
must as well. +1 on that.
The suggested outline at playground:development2 is a good start.
However I'd move the core concepts to the top because they are
probably referenced much in the following pages. I'll merge your
suggestion with the development page when I finish this mail.
Okay, so this became a long mail. Here's the promised summary:
- book authors should author alone
- the community should focus the forces on the "real" documentation at
dokuwiki.org
- don't think like writing a book when working on the wiki
- next task: devel namespace cleanup
Andi
--
splitbrain.org
--
splitbrain.org
--
DokuWiki mailing list - more info at
http://wiki.splitbrain.org/wiki:mailinglist
Other related posts:
