Re: [Geotools-devel] Doc STATUS: initial commit

[Andrea A. <and...@al...>]

Chris Holmes ha scritto:
> First off I apologize for not fully reading this thread, I've been on 
> vacation and there's just a pile of email waiting.  If this question has 
> been resolved just point me at the relevant discussions.
> 
> But _why_ are we reverting back to docbook?  A few years ago we moved to 
> wiki to get _away_ from docbook.  The thought was to lower the barrier 
> to entry for new contributors, just put all the docs on a wiki.  And I 
> think this worked pretty well, we have far more content than we did before.
> 
> I concede that without a solid maintainer it's spiraled a bit out of 
> control.  But wiki lets you do pdf export and the like, so I'm not sure 
> I understand the advantages of docbook?  And the disadvantages are clear 
> and proven for us, we get less documentation contributions when users 
> have to check out and commit on svn just to add a line or two to the docs.
> 
> And I fully support more documention, and if Adrian is super motivated 
> and will only work in docbook, but will make nice, complete guides on 
> his own, that's fine.  Just wanted to raise the fact that we tried 
> docbook before.  It was a bitch to work with, we ended up having all 
> these files to automatically transform from docbook to html, ect. and it 
> ended up being too much overhead.

Ho hum,
I don't know what the others think, I can give you just my motivations
on why I provided my +1.

First off, I keep on loosing my edits when I work with wiki. Edit, preview,
back, forward, boom! And my edit is lost (ok, that's my fault, I'm too
in a hurry when I write docs...).

Second, I usually can't find anything on the confluence site. Even with
Hibernate, that has a easier to work with documentation, I usually get
the "one html page" documentation and then use a lot Firefox search capabilities.

Thrid, wiki is not versioned along with the code, and I'd like it to be
so. Go to: http://docs.codehaus.org/display/GEOSDOC/Documentation
Where's the documentation for Geoserver 1.0? And what version does the
wiki refers to, trunk, latest released version?

Now, usually in my projects I do write documentation in plain XHMTL following
the advices found here:
http://www.binarycloud.com/index.php/Contributor/WritingPackageDocumentation
But since Adrian is the one that propels the new doc effort
I just tried to verify we had tools to edit docbook without too
much effort.

Cheers
Andrea