Andrea Aime wrote:
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...).
Have you tried to 'resume editing'? Confluence actually asynchronously
saves, and if you edit something that you've edited before and lost it
will often have it there.
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.
I agree a one html page could be nice. I'll try to look in to doing
that with confluence. I know you could do it in a way that would be
annoying to maintain, just write out includes for all pages. It'd be
nice if one could fully automate.
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?
Each version is exported at the release and available for download.
And what version does the
wiki refers to, trunk, latest released version?
I'll concede this point, I would like better versioning.
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.
I'm actually ok with it, I don't personally have strong feelings, except
to point at the history, which says that we got much more documentation
when we switched to wiki. I slightly fear us just going around in
circles, when in another couple years someone goes from docbook back to
wiki... I would fight more for GeoServer, as I really like that people
can edit the wiki, but for geotools one could argue programmers know how
to work subversion (though I know I personally added more docs when I
could just write wysiwyg to the wiki).
Chris
Cheers
Andrea
!DSPAM:1003,44eea5be89341362196140!
--
Chris Holmes
The Open Planning Project
http://topp.openplans.org
begin:vcard
fn:Chris Holmes
n:Holmes;Chris
org:The Open Planning Project
adr:;;377 Broadway, 11th Floor;New York;NY;10013;USA
email;internet:[EMAIL PROTECTED]
title:VP, Strategic Development
x-mozilla-html:FALSE
url:http://topp.openplans.org
version:2.1
end:vcard
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Geotools-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geotools-devel
