You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Blevins <da...@gmail.com> on 2011/05/30 01:35:54 UTC

Re: Ideas for Getting the word out -- Examples documentation

On May 28, 2011, at 4:50 PM, David Blevins wrote:

> Some IRC chat resulted in some neat ideas on ways to dramatically improve how easy it is to consume and learn about OpenEJB.
> 
> # Examples
> 
> One thing that hit home is that we have now 46 examples in trunk!!!  Amazing.  However the benefit of that is dramatically reduced as most of them are only available in zip file form.  Links to svn aren't that effective.  And examples change too as the technology improves so keeping wiki pages up to date is hard -- which version of the example do you show?  What if you really want all versions available to see?
> 
> So the idea was to use README files that are formatted in Markdown and use that to generate a page for each example.  No more having part of the example in svn and part of it in confluence and then always breaking.  A stackoverflow inspired solution -- Markdown + Google's prettyprint.
> 
> All the examples are in a zip file that is published in the maven repository, so we could use a maven program to pull them down and extract them to the target directory where we can then do our little page generation.  A stub with those ideas in comments:
> 
>  http://svn.apache.org/repos/asf/openejb/trunk/sandbox/tools/src/main/java/org/apache/openejb/tools/examples/GenerateIndex.java

Haven't seen any discussion specifically about this, so breaking it out as a subtopic so we can hopefully get someone to work on it.  If we keep it simple, it's maybe 500 line mashup of the right libraries.

# The problem

The 3.1.4 and trunk examples are pretty different now, so the confluence content now doesn't line up with what we have:

  http://openejb.apache.org/3.0/simple-stateless-example.html

# Possible fixes

We could update that webpage to reflect the trunk version, but then we'd lose the documentation for the currently supported release which is 3.1.4 and all the pages would reflect stuff that isn't released.

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.

# Previous approaches

At first we started out adding a README.txt to each example and including that in the wiki page.  But that got hard to keep up as to update an example doc you had to tweak both the svn and wiki page at the same time.  So the README.txt files started to get neglected and now most of them are flat out wrong.

# 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.

There are already generic markdown+svn solutions like Maven doxia markdown and the Apache CMS which is markdown based.  We could potentially use those.  If we wanted to go the "build it" route instead of the "reuse" route, it would probably be about 500 lines of code with the right libraries.

# Proof of concept

  http://svn.apache.org/repos/asf/openejb/trunk/openejb3/examples/simple-stateless/README.md
  http://people.apache.org/~dblevins/simple-stateless.html

Side note is that they also happen to look nice on github (hit refresh twice on this page to load up the readme):

  https://github.com/apache/openejb/tree/trunk/openejb3/examples/simple-stateless


-David

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 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 ><>

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>.
(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

Posted by Romain Manni-Bucau <rm...@gmail.com>.
+1

for the design i like "fashion styles" = either very flat either 3D. I'll
try to have a look next week.

- Romain

2011/5/31 David Blevins <da...@gmail.com>

>
> On May 30, 2011, at 12:14 AM, Romain Manni-Bucau wrote:
>
> > are we talking about a openejb communication refactoring?
>
> Wasn't originally thinking so broad, but it has turned into that... which
> is pretty cool :)
>
> > from my side i know there are the website, an apache blog etc...
> >
> > couldn't it be merged into a kind of portal with a blog part, a tutorial
> > part, a community a wiki part etc...? All these pages with a new layout
> and
> > template?
> >
> > IMHO OpenEJB is sexy to use but its communication needs to be more
> > centralized and more attractive.
>
> I'm open to that.  Karan had some ideas on IRC for redoing the front page.
>  My response to that was that maybe we need to redo the whole site.  Perhaps
> a fresh new look in celebration of OpenEJB 4 and TomEE.
>
> I just posted about the CMS.  Might be a good opportunity for some playing.
>
> Sounds like you have some ideas.  Any interest in mocking up something?
>
> The only thoughts I've had on it are that we should go with a standard
> fixed width "one middle column" approach.  Maybe reserve the purple to just
> a top band.
>
>
> -David
>
>

Re: Ideas for Getting the word out

Posted by David Blevins <da...@gmail.com>.
On May 30, 2011, at 12:14 AM, Romain Manni-Bucau wrote:

> are we talking about a openejb communication refactoring?

Wasn't originally thinking so broad, but it has turned into that... which is pretty cool :)

> from my side i know there are the website, an apache blog etc...
> 
> couldn't it be merged into a kind of portal with a blog part, a tutorial
> part, a community a wiki part etc...? All these pages with a new layout and
> template?
> 
> IMHO OpenEJB is sexy to use but its communication needs to be more
> centralized and more attractive.

I'm open to that.  Karan had some ideas on IRC for redoing the front page.  My response to that was that maybe we need to redo the whole site.  Perhaps a fresh new look in celebration of OpenEJB 4 and TomEE.

I just posted about the CMS.  Might be a good opportunity for some playing.

Sounds like you have some ideas.  Any interest in mocking up something?

The only thoughts I've had on it are that we should go with a standard fixed width "one middle column" approach.  Maybe reserve the purple to just a top band.


-David

Re: Ideas for Getting the word out -- Examples documentation

Posted by Romain Manni-Bucau <rm...@gmail.com>.
are we talking about a openejb communication refactoring?

from my side i know there are the website, an apache blog etc...

couldn't it be merged into a kind of portal with a blog part, a tutorial
part, a community a wiki part etc...? All these pages with a new layout and
template?

IMHO OpenEJB is sexy to use but its communication needs to be more
centralized and more attractive.

- Romain

2011/5/30 David Blevins <da...@gmail.com>

>
> On May 28, 2011, at 4:50 PM, David Blevins wrote:
>
> > Some IRC chat resulted in some neat ideas on ways to dramatically improve
> how easy it is to consume and learn about OpenEJB.
> >
> > # Examples
> >
> > One thing that hit home is that we have now 46 examples in trunk!!!
>  Amazing.  However the benefit of that is dramatically reduced as most of
> them are only available in zip file form.  Links to svn aren't that
> effective.  And examples change too as the technology improves so keeping
> wiki pages up to date is hard -- which version of the example do you show?
>  What if you really want all versions available to see?
> >
> > So the idea was to use README files that are formatted in Markdown and
> use that to generate a page for each example.  No more having part of the
> example in svn and part of it in confluence and then always breaking.  A
> stackoverflow inspired solution -- Markdown + Google's prettyprint.
> >
> > All the examples are in a zip file that is published in the maven
> repository, so we could use a maven program to pull them down and extract
> them to the target directory where we can then do our little page
> generation.  A stub with those ideas in comments:
> >
> >
> http://svn.apache.org/repos/asf/openejb/trunk/sandbox/tools/src/main/java/org/apache/openejb/tools/examples/GenerateIndex.java
>
> Haven't seen any discussion specifically about this, so breaking it out as
> a subtopic so we can hopefully get someone to work on it.  If we keep it
> simple, it's maybe 500 line mashup of the right libraries.
>
> # The problem
>
> The 3.1.4 and trunk examples are pretty different now, so the confluence
> content now doesn't line up with what we have:
>
>  http://openejb.apache.org/3.0/simple-stateless-example.html
>
> # Possible fixes
>
> We could update that webpage to reflect the trunk version, but then we'd
> lose the documentation for the currently supported release which is 3.1.4
> and all the pages would reflect stuff that isn't released.
>
> 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.
>
> # Previous approaches
>
> At first we started out adding a README.txt to each example and including
> that in the wiki page.  But that got hard to keep up as to update an example
> doc you had to tweak both the svn and wiki page at the same time.  So the
> README.txt files started to get neglected and now most of them are flat out
> wrong.
>
> # 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.
>
> There are already generic markdown+svn solutions like Maven doxia markdown
> and the Apache CMS which is markdown based.  We could potentially use those.
>  If we wanted to go the "build it" route instead of the "reuse" route, it
> would probably be about 500 lines of code with the right libraries.
>
> # Proof of concept
>
>
> http://svn.apache.org/repos/asf/openejb/trunk/openejb3/examples/simple-stateless/README.md
>  http://people.apache.org/~dblevins/simple-stateless.html
>
> Side note is that they also happen to look nice on github (hit refresh
> twice on this page to load up the readme):
>
>
> https://github.com/apache/openejb/tree/trunk/openejb3/examples/simple-stateless
>
>
> -David
>
>
>
>
>
>