[aerogear-dev] AeroGear project demo planning

Fri Jun 28 11:40:11 EDT 2013

On 27 Jun 2013, at 22:27, Jay Balunas <jbalunas at redhat.com> wrote:

> 
> On Jun 27, 2013, at 3:24 AM, Pete Muir wrote:
> 
>> 
>> On 26 Jun 2013, at 23:15, Jay Balunas <jbalunas at redhat.com> wrote:
>> 
>>> Hi All,
>>> 
>>> As discussed in the team meeting I wanted to restart discussions around the demos for the project.  I know it is long but it is also very important that we agree on our example strategy because it is one of the primary ways that people will learn about AeroGear - especially just starting out.  We also need to balance this with the fact that maintenance of multiple examples can be time consuming (src, docs, tests, etc...).
>>> 
>>> Let me state what I think would be a good model for us at a high level, and then when we come to a consensus about this we can dig into the individual example ideas, specifically around the "showcase" demo (likely in another thread).  
>>> 
>>> All of this is my opinion, not law ;-)
>>> 
>>> _Showcase Demo_
>> 
>> We call this a showcase example.
> 
> +1 I think I like the distinction between example and demo.  
> 
> Example = maintained, more complete, etc...
> Demo = one-time use, or limited in scope somehow
> 
>> 
>>> 
>>> One larger scale demo that we can cover all (or nearly all) of the planned functionality up to 2.0.  There has been several ideas tossed around from stock broker, prodoctor, etc...  I don't want to focus on the specific app at this point.  Functionality would be additive as we completed it, so the idea would need to be easily "upgraded" as we go.
>>> 
>>> The app should include all client types as examples (iOS, Android, Hybrid, Web), have a central backend, be deployable to OpenShift, and run on Wildfly/EAP.  It would require documentation to discuss complexities and usage for an advanced application, but would not need to cover the bread and butter imo (that is what the quickstart tutorials are for).  We would have to commit to long term maintenance of this as well.
>>> 
>>> There are pros and cons for this type of application.  The maintenance and development burden is high.  Also we need to be careful not to devote so much time to the application that it takes on a life of its own.  I.e. we are not really trying to make a fully competitive stock broker app.
>>> 
>>> We also want to consider if/how this application would be deployed to an appstore.  Depending on the application it may be very appropriate for it to be there, but we'll need to discuss. 
>>> 
>>> Does this sounds acceptable as the scope and starting point for a showcase demo?
>>> 
>>> _Topic Demos_
> 
> Topic Examples from this point above :-)
> 
>>> 
>>> I'm not sure about this category of demo yet, but wanted to bring it up.  There are use-cases, and functionality that by their definition are beyond the scope of quickstart, and yet we would likely not want to have the showcase demo be the only location we demo the functionality.
>>> 
>>> The best example of this I can think of is Unified Push.  I think we all agree, just the basic setup and requirements around push make it more than a quickstart.  With the various servers, configuration, certs, etc...  At the same time, we need a demo (both sooner, and simpler) than the showcase demo for the related tutorials, docs, etc…
>> 
>> The definition of a quickstart we are using for JBoss products, and recommend for upstream as well, would include this kind of thing as a quickstart (with a level of Advanced :-). We've said that the defining characteristic of a quickstart is that it shows off a single use case, or a single API - IOW it is really focused on showing the user how to achieve that one thing. The code and set up can be as complex as you like.
> 
> This is interesting and possibly a good distinction, although I'm not sure atm.  Topic examples might also benefit to not be bound by some of the rules of a quickstart - including repo inclusion.  

I'm not sure this is a limiting factor. Submodule can help provide a merged view for the user, but a separate view for developers.

> 
> I'll need to think on this more, and see what others think as well.
> 
>> 
>>> 
>>> So this category would be for this type of "topic" - I could see the possibility of some security functionality falling into this too, but I'm not 100% on that.
>>> 
>>> It would have the same type of requirements as the other demos - docs, tests, maintenance, etc...
>>> 
>>> Pros would be a more focused demo for specific functionality, cons are another non-trivial demo to maintain. 
>>> 
>>> My personal opinion here would be take it on a case by case basis.
>>> 
>>> _Quickstarts_
>>> 
>>> This category sounds like it might be the simplest, but as a whole I think it represents a fairly large amount of work.  Imo a quickstart is a focused demo, that highlights 1-2 specific use-cases.  JDF has a lot of good definitions and requirements for quick starts that we should consider as well, where they don't conflict.  For example build tools, deployment options, etc…
>> 
>> Please help us update our definitions and requirements for native mobile :-) At least we should start to flag general requirements from tech/platform specific requirements.
> 
> +1, I think these will start to come out as we define and develop our quickstarts.  
> 
>> 
>>> 
>>> The trick here comes with how to manage and handle all of our different "parts".  Do we group by client type, by functionality, etc...  So for example, take a security related quickstart.  It should show how to integration security across the various client types.  Is that 1 quickstart for security, or 3 by client type.
>> 
>> For product quickstarts, we've gone for a flat structure, with no hierarchy. This has worked well for us, and it's only as we approach 100 quickstarts that we've needed to introduce a hierarchy. So IMO I would start simple (flat structure) and do a restructure once you've got feedback from both the authors and the users of quickstarts about what isn't and is working.
> 
> KISS at first, then see where it leads.  Makes sense, my only concern is that with the # of client types that will regularly be needed for most quickstarts it might need more structure.  Then there is also the cookbook thoughts that would be like sub-categories based on client type.
> 
> Not sure I feed like either approach is right atm.
> 
>> 
>>> 
>>> Related to this is the cookbook idea that the Android team is using.  Imo I think it is VERY important that all of our client types share a similar approach (cookbook or not).  We don't want completely different approaches by client type.  If we do group quickstarts (some or all) by client how will we handle common server-side functionality such as that security example above.
>>> 
>>> All of these items get complicated quickly, but I think we need to nail this down asap because we should start thinking about our quickstart libraries soon imo.
>>> 
>>> _One off examples_
>>> 
>>> Another type of example was mentioned in the ML, and that is of one-off examples for presentations, blogs, etc...  Imo these are useful, and likely needed some of the time.  
>>> 
>>> I think we should re-use our other examples when possible, but I also know that will not alway work for various reasons.  These examples carry no maintenance expectations, and should not be in the AeroGear repositories either imo.
>>> 
>>> I also think it is possible for one-off examples to "become" quickstarts, but would have to meet the standards for a quickstart as we describe them.
>> 
>> We call this type of example a "demo" - something that shows of functionality, but won't necessarily be maintained etc.
> 
> +1
> 
>> 
>>> 
>>> _Repositories_
>>> 
>>> This is a related topic that I think will likely become its own thread or document, and that is about repository usage for the example types above.  In general we need a better policy imo around this topic in general.
>>> 
>>> * Showcase example: I believe it should have a single repository with /server, /client, and /docs directories as needed.  I believe having separate repositories is confusing and leads to clutter.  The intent of the showcase app is to demo how everything integrates in one place, and should be easily accessed.
>>> 
>>> * Topic examples: I believe these should have a similar requirement as the showcase example.  The point of the topic example is to cover a specific topic, not specific individual clients.  
>>> 
>>> * Quickstart examples:  This again gets complicated, and may depend on the way we choose  to group them.  However we group them, I think we should have a limited number of *-quickstart repositories, we should not have a repo for each quickstart.  We'll need to discuss this as we discuss quickstart planning in general.
>>> 
>>> * One off examples: should not be in AeroGear's repository at all.  Imo, if we aren't committing to maintain it we should not have it our repository. 
>>> 
>>> _Forge and JBDS_
>>> 
>>> We also need to discuss how any of these examples relate to forge and JBDS efforts.  At the very least, imo, some of our quickstarts should be based on scaffolding, and tooling.  Imo many of the example (where possible) should be compatible with forge, and JBDS.
>>> 
>>> Not all examples would need to be compatible.  Obviously that does not apply to iOS, and we would need to balance the effort required on a case-by-case basis for others.  It just might not make sense or have a different target than forge or JBDS.  That is fine, I don't want to use this as a handicap, but we should be considering both of these as we go.
>>> ----------
>>> 
>>> Again, I don't want this thread to break down into specific use-case discussions, I want us to discuss the example strategies for the project, then we can kick off separate thread for break down specific examples, and plans for them.
>>> 
>>> -Jay
>>> _______________________________________________
>>> aerogear-dev mailing list
>>> aerogear-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>> 
>> 
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
> 
> 
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev