You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by Marius Kruger <am...@gmail.com> on 2011/07/10 00:42:03 UTC
Re: Ideas for Getting the word out -- Examples documentation
(sorry for resurrecting the topic and maybe talking about stuff that
was already dealt with)
On 30 May 2011 01:35, David Blevins <da...@gmail.com> wrote:
...
> We could create a new space for 4.0 and copy the examples there and update them there, but our track record on getting any content at all up in the wiki for each example is incredibly poor already. Currently only about 13 of 46 examples are documented in the wiki. No way we'd do any better with double the pages to maintain.
I count 15 examples on http://openejb.apache.org/examples.html
It is terrible that so few are effectively visible to the public with
no mention that there are actually more available. (I know I wish I
realised that before now, I assumed they were all there)
I think an easy first step is to at least mention that more examples
are available here:
http://svn.apache.org/viewvc/openejb/trunk/openejb3/examples/
(I tried to do that but it seems I don't have permission (username: amanica))
> # Better possible solution
>
> It's a bit of a nightmare. Seems if we ditched the wiki part of it completely and just made the README the sole source of info instead of splitting it, converted it to markdown which looks fine in plain text, we might stand a better chance of keeping things current.
+1 for that
* stay DRY, don't make extra work, things should just appear :-)
* configure once to maybe get updated by the continuous integration
server and have them updated forever.
* I'd say keep them separate for each version. That is how bazaar dvcs
does it [1]
(disclaimer: I've worked on bazaar a bit, having to write eg.
changelogs in rest syntax[2],
I think it works quite nice, they use sphinx[3] to process it)
* maybe I can somehow lend a hand with some of this, time permitting.
(not promising anything :-)
--
[1] http://doc.bazaar.canonical.com/en/
[2] http://docutils.sourceforge.net/rst.html
[3] http://sphinx.pocoo.org/
<>< Marius ><>
Re: Ideas for Getting the word out -- Examples documentation
Posted by stratwine <to...@gmail.com>.
Looks cool ! I'll join in and do some CSS styling tomorrow.
-Vishwa
--
View this message in context: http://openejb.979440.n4.nabble.com/Ideas-for-Getting-the-word-out-tp3558206p3657785.html
Sent from the OpenEJB Dev mailing list archive at Nabble.com.
Re: Ideas for Getting the word out -- Examples documentation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
for the theme i'll maybe have a look monday evening but before i want to add
the scan of .xml/properties which can be cool too.
well, if anybody wants to make a better template we can work together to
make it better than it is today :)
- Romain
2011/7/10 David Blevins <da...@gmail.com>
>
> On Jul 9, 2011, at 3:42 PM, Marius Kruger wrote:
>
> > (sorry for resurrecting the topic and maybe talking about stuff that
> > was already dealt with)
> >
> > On 30 May 2011 01:35, David Blevins <da...@gmail.com> wrote:
> > ...
> >> We could create a new space for 4.0 and copy the examples there and
> update them there, but our track record on getting any content at all up in
> the wiki for each example is incredibly poor already. Currently only about
> 13 of 46 examples are documented in the wiki. No way we'd do any better
> with double the pages to maintain.
> >
> > I count 15 examples on http://openejb.apache.org/examples.html
> > It is terrible that so few are effectively visible to the public with
> > no mention that there are actually more available. (I know I wish I
> > realised that before now, I assumed they were all there)
> > I think an easy first step is to at least mention that more examples
> > are available here:
> > http://svn.apache.org/viewvc/openejb/trunk/openejb3/examples/
> > (I tried to do that but it seems I don't have permission (username:
> amanica))
>
> Added you to the openejb-contributors group so you can edit docs.
>
> >> # Better possible solution
> >>
> >> It's a bit of a nightmare. Seems if we ditched the wiki part of it
> completely and just made the README the sole source of info instead of
> splitting it, converted it to markdown which looks fine in plain text, we
> might stand a better chance of keeping things current.
> >
> > +1 for that
> > * stay DRY, don't make extra work, things should just appear :-)
> > * configure once to maybe get updated by the continuous integration
> > server and have them updated forever.
> > * I'd say keep them separate for each version. That is how bazaar dvcs
> > does it [1]
> > (disclaimer: I've worked on bazaar a bit, having to write eg.
> > changelogs in rest syntax[2],
> > I think it works quite nice, they use sphinx[3] to process it)
> > * maybe I can somehow lend a hand with some of this, time permitting.
> > (not promising anything :-)
>
> Any help is more than welcome :) Romain did some great work in this area
> on a stackoverflow inspired example listing:
>
> http://ci.apache.org/projects/openejb/examples-generated/
>
> Still very lacking in the actual README files but is a concrete step in the
> right direction. At this point I think it's waiting for someone with some
> better CSS skills to make it look pretty. Would be great if we could use
> the same look and feel as the website. All templates and things are here:
>
> http://svn.apache.org/repos/asf/openejb/trunk/sandbox/tools/
>
> Any hacking at all in this area is totally welcome. Any features or bells
> and whistles are great. Anything that makes digesting such a large quantity
> of examples that much easier. Once we get CDI examples in as well, we'll
> easily reach 100 examples.
>
>
> -David
>
>
Re: Ideas for Getting the word out -- Examples documentation
Posted by David Blevins <da...@gmail.com>.
The real page is here:
https://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJBx30&title=Examples+Table
Try that one. I think we have it setup so that the main site (OPENEJB) as stricter perms than the documentation space (OPENEJBx30).
Hopefully it will all be a matter of simple patches pretty soon :)
-David
On Jul 11, 2011, at 3:42 PM, Karan Malhi wrote:
> Hi Marius,
>
> This is a bit strange. I just checked and you are in the OpenEJB
> contributors group, which means you should be able to add content.
>
> On Sun, Jul 10, 2011 at 1:15 PM, Marius Kruger <am...@gmail.com> wrote:
>> On 10 July 2011 01:46, David Blevins <da...@gmail.com> wrote:
>> ...
>>
>>> Added you to the openejb-contributors group so you can edit docs.
>>>
>>
>> thank you and Karan for trying to add me, but it did not seem to work.
>> If I try to edit the examples page:
>> https://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJB&title=Examples
>> I still get "You are not permitted to perform this operation."
>>
>> --
>> <>< Marius ><>
>>
>
>
>
> --
>
> Karan Singh Malhi
> twitter.com/KaranSinghMalhi
Re: Ideas for Getting the word out -- Examples documentation
Posted by Karan Malhi <ka...@gmail.com>.
Hi Marius,
This is a bit strange. I just checked and you are in the OpenEJB
contributors group, which means you should be able to add content.
On Sun, Jul 10, 2011 at 1:15 PM, Marius Kruger <am...@gmail.com> wrote:
> On 10 July 2011 01:46, David Blevins <da...@gmail.com> wrote:
> ...
>
>> Added you to the openejb-contributors group so you can edit docs.
>>
>
> thank you and Karan for trying to add me, but it did not seem to work.
> If I try to edit the examples page:
> https://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJB&title=Examples
> I still get "You are not permitted to perform this operation."
>
> --
> <>< Marius ><>
>
--
Karan Singh Malhi
twitter.com/KaranSinghMalhi
Re: Ideas for Getting the word out -- Examples documentation
Posted by Marius Kruger <am...@gmail.com>.
On 10 July 2011 01:46, David Blevins <da...@gmail.com> wrote:
...
> Added you to the openejb-contributors group so you can edit docs.
>
thank you and Karan for trying to add me, but it did not seem to work.
If I try to edit the examples page:
https://cwiki.apache.org/confluence/pages/editpage.action?spaceKey=OPENEJB&title=Examples
I still get "You are not permitted to perform this operation."
--
<>< Marius ><>
Re: Ideas for Getting the word out -- Examples documentation
Posted by David Blevins <da...@gmail.com>.
On Jul 11, 2011, at 9:09 AM, stratwine wrote:
>
> David Blevins-2 wrote:
>>
>>
>> Anything that makes digesting such a large quantity of examples that much
>> easier.
>>
>>
>
> An option to view examples grouped as trails maybe ? Something like the
> http://download.oracle.com/javase/tutorial/java/data/characters.html java
> trail ?
That could be really good. Shouldn't be too hard to generate that. Could even use a trails.properties file:
learning_ejb = simple-stateless, simple-stateful, simple-singleton
Then just link them together with "previous" and "next".
Or maybe something else entirely... just brainstorming :)
-David
Re: Ideas for Getting the word out -- Examples documentation
Posted by stratwine <to...@gmail.com>.
David Blevins-2 wrote:
>
>
> Anything that makes digesting such a large quantity of examples that much
> easier.
>
>
An option to view examples grouped as trails maybe ? Something like the
http://download.oracle.com/javase/tutorial/java/data/characters.html java
trail ?
--
View this message in context: http://openejb.979440.n4.nabble.com/Ideas-for-Getting-the-word-out-tp3558206p3660003.html
Sent from the OpenEJB Dev mailing list archive at Nabble.com.
Re: Ideas for Getting the word out -- Examples documentation
Posted by David Blevins <da...@gmail.com>.
On Jul 9, 2011, at 3:42 PM, Marius Kruger wrote:
> (sorry for resurrecting the topic and maybe talking about stuff that
> was already dealt with)
>
> On 30 May 2011 01:35, David Blevins <da...@gmail.com> wrote:
> ...
>> We could create a new space for 4.0 and copy the examples there and update them there, but our track record on getting any content at all up in the wiki for each example is incredibly poor already. Currently only about 13 of 46 examples are documented in the wiki. No way we'd do any better with double the pages to maintain.
>
> I count 15 examples on http://openejb.apache.org/examples.html
> It is terrible that so few are effectively visible to the public with
> no mention that there are actually more available. (I know I wish I
> realised that before now, I assumed they were all there)
> I think an easy first step is to at least mention that more examples
> are available here:
> http://svn.apache.org/viewvc/openejb/trunk/openejb3/examples/
> (I tried to do that but it seems I don't have permission (username: amanica))
Added you to the openejb-contributors group so you can edit docs.
>> # Better possible solution
>>
>> It's a bit of a nightmare. Seems if we ditched the wiki part of it completely and just made the README the sole source of info instead of splitting it, converted it to markdown which looks fine in plain text, we might stand a better chance of keeping things current.
>
> +1 for that
> * stay DRY, don't make extra work, things should just appear :-)
> * configure once to maybe get updated by the continuous integration
> server and have them updated forever.
> * I'd say keep them separate for each version. That is how bazaar dvcs
> does it [1]
> (disclaimer: I've worked on bazaar a bit, having to write eg.
> changelogs in rest syntax[2],
> I think it works quite nice, they use sphinx[3] to process it)
> * maybe I can somehow lend a hand with some of this, time permitting.
> (not promising anything :-)
Any help is more than welcome :) Romain did some great work in this area on a stackoverflow inspired example listing:
http://ci.apache.org/projects/openejb/examples-generated/
Still very lacking in the actual README files but is a concrete step in the right direction. At this point I think it's waiting for someone with some better CSS skills to make it look pretty. Would be great if we could use the same look and feel as the website. All templates and things are here:
http://svn.apache.org/repos/asf/openejb/trunk/sandbox/tools/
Any hacking at all in this area is totally welcome. Any features or bells and whistles are great. Anything that makes digesting such a large quantity of examples that much easier. Once we get CDI examples in as well, we'll easily reach 100 examples.
-David
Re: Ideas for Getting the word out -- Examples documentation
Posted by Karan Malhi <ka...@gmail.com>.
On Sat, Jul 9, 2011 at 6:42 PM, Marius Kruger <am...@gmail.com> wrote:
> (sorry for resurrecting the topic and maybe talking about stuff that
> was already dealt with)
I would say thank you for bringing our attention back to it.
>
> On 30 May 2011 01:35, David Blevins <da...@gmail.com> wrote:
> ...
>> We could create a new space for 4.0 and copy the examples there and update them there, but our track record on getting any content at all up in the wiki for each example is incredibly poor already. Currently only about 13 of 46 examples are documented in the wiki. No way we'd do any better with double the pages to maintain.
>
> I count 15 examples on http://openejb.apache.org/examples.html
> It is terrible that so few are effectively visible to the public with
> no mention that there are actually more available. (I know I wish I
> realised that before now, I assumed they were all there)
> I think an easy first step is to at least mention that more examples
> are available here:
> http://svn.apache.org/viewvc/openejb/trunk/openejb3/examples/
> (I tried to do that but it seems I don't have permission (username: amanica))
>
You should now have access to edit the page
>> # Better possible solution
>>
>> It's a bit of a nightmare. Seems if we ditched the wiki part of it completely and just made the README the sole source of info instead of splitting it, converted it to markdown which looks fine in plain text, we might stand a better chance of keeping things current.
>
> +1 for that
> * stay DRY, don't make extra work, things should just appear :-)
> * configure once to maybe get updated by the continuous integration
> server and have them updated forever.
> * I'd say keep them separate for each version. That is how bazaar dvcs
> does it [1]
> (disclaimer: I've worked on bazaar a bit, having to write eg.
> changelogs in rest syntax[2],
> I think it works quite nice, they use sphinx[3] to process it)
> * maybe I can somehow lend a hand with some of this, time permitting.
> (not promising anything :-)
All ideas are welcome. Anything to make it simpler and up-to-date.
>
> --
> [1] http://doc.bazaar.canonical.com/en/
> [2] http://docutils.sourceforge.net/rst.html
> [3] http://sphinx.pocoo.org/
> <>< Marius ><>
>
--
Karan Singh Malhi
twitter.com/KaranSinghMalhi
Re: Ideas for Getting the word out -- Examples documentation
Posted by Marius Kruger <am...@gmail.com>.
On 10 July 2011 00:42, Marius Kruger <am...@gmail.com> wrote:
> I think an easy first step is to at least mention that more examples
> are available
[done]
I added the following to
https://cwiki.apache.org/confluence/display/OPENEJBx30/Examples+Table
, please tweak if you can do better:)
But I don't see the main examples page[1] updating, I assume there is
some reviewing or scheduled update that will make that happen later.
Or is the pages actually maintained separately?
==
Unfortunately all the examples are not documented here yet, more
examples can be [browsed in version
control|http://svn.apache.org/viewvc/openejb/trunk/openejb3/examples/]
or check it out with subversion ({{svn co
http://svn.apache.org/repos/asf/openejb/trunk/openejb3/examples}}).
==
[1] http://openejb.apache.org/examples.html
--
<>< Marius ><>