Why is it 30MB? What's in it? Are there a lot of images?
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
