Having the documentation available for download from the website has been spinning on my head for quite some time but not having access to the file system where those files are server from has proven to be a major pain.
I like the HTML version better that the PDF because most of the articles are in
fact tutorials with sample apps. Most of the time these apps are provided as
zip files and you can not get them from a PDF copy, can you !?
Back to the issue, we currently don't have access to the autoexported files in
first place. Second, the autoexport plugin has some issues with the URLs and
all the Confluence native content still points to the source Confluence server.
Not sure how to better explain this but basically the exported content can be
viewed off line only partially.
In addition to that one there are a few other issues already known and reported
for that plugin that we should address or help to get resolved ->
http://could.it/bugs/browse/EXP
There are a bunch more sample applications in the cwiki that I would like to have
them available form the web site ->
http://cwiki.apache.org/GMOxDOC11/sample-applications.html
This last comment makes me think that maybe we should review and look for a
better integration between the web site and cwiki. Comments welcome!
I'll keep looking for a way to get the cwiki content retrieved and massaged in
a way that can be viewed off line, but this method has to be quick and easy
enough to catch up with the daily updates to the cwiki.
Cheers!
Hernan
Jeff Genender wrote:
Can we make the doc a separate download? I think it would still be a
great thing for people to have locally.
Jeff
Hernan Cunico wrote:
We decided to remove the docs from the dist because of the size. The
Geronimo v1.0 doc was (still is) over 30 Mb.
In addition, most of the doc is developed around and after the next
version of Geronimo is released. The current documentation work is
mainly being done around v1.1 and v1.1.1.
A few things we could do to workaround this issue would be a selective
download of the documentation. Whoever is interested in having the doc
available off line could download it as a "plugin" or a zip file
directly from the website and keep it up to date locally.
To do this we first would need to fix the autoexport plugin used in
confluence to resolve some URL mapping issues and second get access to
brutus file system to get our hands on the exported wiki content or
modify the plugin (again) so we can choose multiple locations for the
exported material. One being the directory structure where the files are
served from and the other maybe an svn repo or a remote location where
we would actually have physical access to those files.
But this wont address the issue of releasing a new version with a full
doc included in the dist.
Cheers!
Hernan
Geir Magnusson Jr. wrote:
Hernan Cunico wrote:
I certainly don't mind being pointed as a reference ;-)
Sanjeeva, I joined the Geronimo project sometime before M5 was
released and I been working hard to give Geronimo the best
documentation possible, well at least I'm trying my best.
Documentation has a lot of visibility, everybody needs some form of
documentation at some point. There are a lot more users needing to
consume that documentation than people willing/available to
contribute to the development of such doc. That's why the
contributions are so valuable.
Can we get the docs into the next release? IIRC, our last release was
doc-free...
geir
Contributing with the documentation however is part of the "deal",
contributors have to be very vocal about their contributions.
Currently there is no such a thing as automatic notification to the
dev/user list of all the new docs available. Even if there would be
such mechanism I would still prefer to communicate those updates to
the lists myself asking for feedback and inviting others to
contribute too. It is not just about the documentation itself but
also fostering the community around it.
Using JIRA may be a way to keep track of the docs contributed but as
I mentioned before, I would still prefer to communicate the
documentation updates to the lists myself and ask for user feedback.
Committertship is something that wont happen overnight, but it will
happen after sustained contributions towards the project and the
community. I never thought I would become a committer working on the
documentation ( and other things ;-) ) but it happened, not to
mention joining the PMC.
One last piece of advice (personal) for the folks at LSF, keep up the
good work and let the community know what they are working on. Look
for what the Geronimo community needs and help out in that
area/topic, communicate their plans.
HTH
Cheers!
Hernan
Jacek Laskowski wrote:
On 10/30/06, Sanjiva Weerawarana <[EMAIL PROTECTED]> wrote:
There are three folks working on Geronimo docs as part of a Lanka
Software Foundation (LSF) project to get a Geronimo project going from
Sri Lanka. All the work they're doing right now is apparently going in
thru the wiki- which means there's basically no visibility for their
work towards earning karma towards committership an other higher forms
of life ;-).
Hey Sanjiva,
One way to handle it is to set up a Confluence notification to make
sure we're all aware of any doc contribution (as Guillaume pointed
out).
There's another less-technical, more-community-oriented one - sending
emails to mailing lists ([EMAIL PROTECTED] preferred) when a part of the
documentation set is finished. I don't think there's a better way to
earn more visibility than having end users expressed their
gratefulness for the work done. The often the LSF documentation group
announce it to the user mailing list the merrier. I also think that
it's one of the best way to invite others to contributing to
documentation and thus getting more visibility among the community.
In the Web services projects we strongly encourage documentation
contribs and bring people in as committers only for that. How do you
guys handle this if people do docs thru the wiki and those contribs
are
not visible?
They're always visible, but it can take a longer time comparing to the
source code's contribution. I hope Hernan doesn't mind if I mentioned
him as an excellent example of how Apache Geronimo project expressed
its thanks for his contribution to the documentation area and
eventually got his commit karma.
Jacek
