Re: [Fwd: Visibility for Geronimo Documentation Work]

[Jeff Genender <jg...@apache.org>]

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 <sa...@opensource.lk> 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 (user@geronimo 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
>>>>
>>>
>>
>>

Re: [Fwd: Visibility for Geronimo Documentation Work]

[Matt Hogstrom <ma...@hogstrom.org>]

A PDF or zip of html would be way cool.

Re: [Fwd: Visibility for Geronimo Documentation Work]

[Hernan Cunico <hc...@gmail.com>]

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 <sa...@opensource.lk> 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 (user@geronimo 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
>>>>>
>>>
> 

Re: [Fwd: Visibility for Geronimo Documentation Work]

[Hernan Cunico <hc...@gmail.com>]

Yup, there are lots of images and sample apps.

Geir Magnusson Jr. wrote:
> 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 <sa...@opensource.lk> 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 (user@geronimo 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
>>>>>>
>>>>
>>
> 

Re: [Fwd: Visibility for Geronimo Documentation Work]

["Geir Magnusson Jr." <ge...@pobox.com>]

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 <sa...@opensource.lk> 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 (user@geronimo 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
>>>>>
>>>
>