Re: [jdf-dev] How do I?

On 23 Jul 2012, at 14:00, Jay Balunas wrote: > > On Jul 23, 2012, at 8:28 AM, Pete Muir wrote: > >> Hi Jay/Brian, >> >> On 23 Jul 2012, at 13:17, Jay Balunas wrote: >> >>> >>> On Jul 21, 2012, at 12:58 PM, Brian Leathem wrote: >>> >>>> I'm keen on creating such howto (err... "How do I?") content. We have >>>> some now, but it is very wiki/text based and not *easy* for the user to >>>> consume. >> >> Definitely a good thing we are pushing this then :-) >> >>>> >>>> What's the timing of this? >> >> For jdf 2.0, which is currently planned to go Final for the end of September, in time for WFK 2.1. >> >> In order to get it into jdf 2.0 with ample time to settle it in, I suggested the end of August as the time for us to get the drafts done, ready for review. >> >>>> Ideally I would like to time the creation of >>>> this content with the new RichFaces awestruct site (which I've >>>> tentatively slated for August). That would also make it easier to share >>>> the same content source between the JDF and RF sites. We'd then have >>>> these introductory howtos in the both the JDF and RF sites, with JDF >>>> linking to the RF site for "more details" and more howtos etc. >> >> Sounds good to me. >> >> We already pull in 4 other repos as submodules into the jdf site, and i'm very happy to add more. To date, the approach has been to simply manually update these, but as the number expands, we'll want to centralise control of this into the site generation. Today, we have a yaml file that specifies the versions of guides (e.g. ticketmonster, quickstarts, migration guides) that we consume, so I probably will use this, and add updating and setting the correct version of the submodule to the site generation. >> >>>> >>>> That way those who know they want to use RF will find the content on the >>>> RF site, and those who don't know which view technology they want will >>>> "stumble" across it while browsing the JDF site. I like it! >>> >>> An arrangement like what you have described seems a good compromise and more maintainable in the long run. >> >> I'm sorry, I never meant to imply that this should replace in anyway the project specific documentation. >> >> This is really supposed to be part of the route in to JBoss technologies. So we address the general question of "how do I create an app using JBoss", and then feed over to the projects, depending on the option the person picks. We can host more, or less, of the docs depending on what the project wants (e.g. we hold quite a lot of the JBoss AS tutorials, but could hold less of the Aerogear ones). All I'm sure we need to hold in jdf is those first steps - "how do I start with RichFaces", and "how do I add RichFaces". Once they want to know "how do I add a datatable with RichFaces" then that way out of scope for jdf, and I wouldn't even want that question on the jdf site. >> >> So the scope is limited, for the projects mentioned below, to the topics mentioned below. Any expansion of scope would need a lot of discussion. >> >> Jay, WDYT, can we do this with the Aerogear docs too, given the requirements I wrote out before? > > Yes, this seems reasonable. We'll still have our own "get started", but we'll make it consumable from JDF with links to AeroGear pages for more detailed breakdowns. To be clear, we are still talking about the guide being self contained, but linking to aerogear for guides on other topics (such as security etc etc)

> > Besides the content updates we discussed already, what is needed by JDF to pull in RichFaces & AeroGear docs? If we can do the content changes + have this on git in a consumable fashion (e.g. asciidoc, textile, markdown, haml) then we are conceptually ok. There may be some details to sort out (e.g. needing a tag) still, of course :-)

> >> >>> >>>> >>>> Brian >>>> >>>> Ps. I was unable to successfully type JDF in this e-mail without first >>>> typing JSF. :P >>>> >>>> On 12-07-20 06: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(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/jdf-dev >>> >> >