[jdf-dev] How do I?

Fri Jul 20 13:39:21 EDT 2012

On Jul 20, 2012, at 12:09 PM, Pete Muir wrote:

> Hi
> 
> On 20 Jul 2012, at 15:32, Jay Balunas wrote:
> 
>> Hi Pete,
>> 
>> I like the idea of a central FAQ.
> 
> I'm trying to avoid the term FAQ, as it comes with a loaded meaning, which typically means "stuff that should really be in the docs, or is just odd, but we can't properly fix for some reason". 
> 
> Instead, this is more of a question/task driven approach to learning, where we identify common things that people need to do, and address them.

Makes sense, FAQs do have baggage

> 
>> However I'm assuming in the answers to these questions we can link to existing project material that in many cases already exists that cover these topics.
> 
> No. We're strongly of the opinion that that tutorials and guides work much better when the user can work through them step by step, in one place, without having to switch out. Every time you make someone click a link, they are more likely to give up. Furthermore, we introduce quality control problems when we link out, as we don't have control over the other end of the link
> 
> These guides should be self contained.

So here lies the problem though.  The "parent" projects, and I don't just mean AeroGear, need to have their own tutorials, video's, webinars, etc... to be a healthy and complete open source project.  Many project teams have already spent a lot of time making these.  If we need to duplicate the majority of these in JDF it could be quite time consuming, not to mention confusing for users searching for them.

I'm not just thinking about initial time cost either.  This would introduce a whole new place where this information needs to be updated and maintained.

> 
>> Much like the quickstarts I don't want to have two places to maintain. 
> 
> We can certainly look at including segments of the document from other sources, but the end result should appear to be a single source (i.e. consistent language, l&f etc)

If there is a good way of doing this it might work out, but would the cure be worse then the problem.  

In other words if now there are strict requirements on other projects docs to be in specific formats, notifications of updates, scripts, and merges it might not be the best solution.

> 
>> 
>> For example the answer to "How do I build a new HTML5 application, and get it deployed to the cloud, all in ten minutes?" is covered in AeroGear's wiki (sbs is migrating to asciidoc/site).
>> 
>> * Docs:
>> * https://github.com/aerogear/docs.aerogear.org/blob/master/guides/GetStartedHTML5MobileWeb.asciidoc
>> * https://github.com/aerogear/docs.aerogear.org/blob/master/guides/HTML5AppsToOpenshift.asciidoc
>> * Video:
>> * http://vimeo.com/39606090
> 
> Actually, this topic was based on a different approach, using Forge and JQuery mobile to do RAD. The latter guide here is really the "How do I create a new HTML 5 Application". If it makes sense to you, we can try to share this single document as the one for this How do I? 

I think using forge and using JBDS are likely two separate items for different developers.  Might end up in the same place, but the way to get there is diff.

> 
> I will need to request some changes, on initial look:

Some are just a good ideas and are no problem (besides the jira's and time to do them), others are more time consuming than some projects may have time for (thinking mainly of video's for each)

> 
> * It will need to target both EAP and AS, JBDS and JBoss Tools (as per the normal quickstart etc. guidelines)
> * The command line stuff (archetype, deployment, test running) needs swapping with the JBoss Tools section, and probably moving to an appendix
> * We'll need a specific video covering exactly the steps in the document
> * A split, so that we can dump your intro for the question
> 
> WDYT?

I guess what I'm saying is that imo the issues above would out weight the benefits of having all the tutorials/videos [content] in one place.  Personally I would want to know I was on RichFaces site when learning about RichFaces, or forge, etc...

JDF would certainly have (and has) it's own sets of cross project examples, and tutorials, and I think it should be a hub for this knowledge, but not always the keeper of it.  

> 
>> 
>> Is this what you are thinking?
>> 
>> -Jay
>> 
>> On Jul 20, 2012, at 9:31 AM, Pete Muir wrote:
>> 
>>> All,
>>> 
>>> For jdf 2.0 we want to introduce a new top level area to the site, "How do I?".
>>> 
>>> Reviewing the existing areas:
>>> 
>>> * Quickstarts: small, runable apps which show how to use an API
>>> * Examples: larger runable apps, which show how to fulfil a range of use cases
>>> * Migration guides
>>> * Stacks: recommended stacks of libraries and frameworks to use together
>>> 
>>> We quickly realised we had nowhere we could address questions like:
>>> 
>>> "How do I add RichFaces to my application?
>>>  You created a Java EE application using JBDS, and now you want to add RichFaces"
>>> 
>>> "How do I build a new HTML5 application, and get it deployed to the cloud, all in ten minutes?
>>>  You're interested in the RAD options that JBoss offered, and want to see how to get started"
>>> 
>>> "How can I make the most of OpenShift with JBoss?
>>>  You're used to JBoss software, and want to explore how OpenShift can help you"
>>> 
>>> We're proposing to add a new top level area, named "How do I?" that contains articles that address each of these topics.
>>> 
>>> Initially, we have identified these questions as the ones that we want to answer (either because they question always comes up, or because we already have material for it). In the list below, I've volunteered people to take some of the topics, and if anyone else can help out, that would be much appreciated.
>>> 
>>> "How do I add RichFaces to my application?
>>>  You created a Java EE application using JBDS, and now you want to add RichFaces"  <--- Brian Leatham/RichFaces team (I'm not aware of any content we have today)
>>> 
>>> "How do I create a new RichFaces application?
>>>  You're just starting out, and want to create a new RichFaces application"  <--- Brian Leatham/RichFaces team (Based on archetype via JBDS)
>>> 
>>> "How do I add Errai to my application?
>>>  You created a Java EE application using JBDS, and now you want to add Errai"  <--- Lincoln Baxter/Errai team (I'm not aware of any content we have today)
>>> 
>>> "How do I create a new Errai application?
>>>  You're just starting out, and want to create a new Errai application"  <--- Lincoln Baxter/Errai team (Based on archetype via JBDS)
>>> 
>>> "How do I add HTML5 to my application?
>>>  You created a Java EE application using JBDS, and now you want to add HTML5"  <--- Marius Bogoevici (I'm not aware of any content we have today)
>>> 
>>> "How do I create a new HTML5 application?
>>>  You're just starting out, and want to create a new HTML5 application"  <--- Jay Balunas/Aerogear team (Based on archetype via JBDS)
>>> 
>>> "How do I build a new HTML5 application, and get it deployed to the cloud, all in ten minutes?
>>>  You're interested in the RAD options that JBoss offered, and want to see how to get started" <--- Pete Muir (based on the demo that Pete and Marius did at JBoss World 2012)
>>> 
>>> "How can I make the most of OpenShift with JBoss?
>>>  You're used to JBoss software, and want to explore how OpenShift can help you"  <-- Pete Muir (based on Pete's JBoss + OpenShift RAD talk)
>>> 
>>> Any other topics, please let us know :-)
>>> 
>>> Obviously, we are still establishing this an area, so we don't have 100% locked down the format, content types etc. My proposal is that we offer at least:
>>> 
>>> * the question, and the short use case that the person is trying to walk through (as I've written out here)
>>> * an article, walking the person through the solution, including screenshots, sample output etc. where relevant
>>> * a video, showing the person the solution
>>> 
>>> and optionally:
>>> 
>>> * a script, which walks someone who is trying to do a demo, the necessary steps
>>> * presenter notes, which highlight key things to talk about whilst doing the demo
>>> 
>>> Of course, JBDS should be used throughout.
>>> 
>>> "Volunteers", please let me know if you are ok with this :-) We would be looking for this to be done by the end of August. I will try to do a prototype one soon, to give some guidance.
>>> 
>>> Pete
>>> _______________________________________________
>>> jdf-dev mailing list
>>> jdf-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/jdf-dev
>> 
>> _______________________________________________
>> jdf-dev mailing list
>> jdf-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/jdf-dev
> 