Literally years ago, I pitched an idea for a JBoss cookbook, the tutorial site of my dreams, to Dan which I belive shares the same goals. Feel free to incorporate any ideas you find useful. If this is something we can make happen, I would love to be involved.
JBoss.org Cookbook Proposal
What is it?:
The JBoss cookbook is an idea for a crowd-sourced instructional website in which examples and tutorials, such as those regarding Enterprise Java, are presented in a recipe format. A recipe is a short, succinct tutorial or example that is limited in scope, illustrates a specific technology or technique, and includes a link to download the source.
The idea is inspired by JavaAlmanac.com, in which a basic Java techniques are explained using short articles and code samples of a very narrow focus. The cookbooks idea differs from the almanac in that it will be crowd-sourced and each tutorial will all the code needed to run the example as Enterprise Java often requires more configuration and boilerplate to get started. Each recipe will also need their own discussion page in which folks can ask provide feedback or ask for clarification.
In order to really thrive, community members will need to be able to submit recipes themselves. I envision recipes having two states: verified and listed in the main index and unverified, but searchable. Just like in JavaAlmanac, there should be a main index, which is curated by trusted senior members, of verified recipes. However, unverified recipes also need a voting mechanism in which the crowd can mark a recipe as valuable to get noticed by the curators for excellence or flagged for being abusive, erroneous, or a bad practice.
JBoss wants to drive adoptions and community participation. Adoption starts with desire and inspiration. A user is inspired by the promise of a technology and develops a desire to solve a problem within their organization using a JBoss product. There are many steps between desire and adoption in which the user is presented with an opportunity to fail, get frustrated, or lose interest.
To help users transition from the desire to use a product to actually getting the product implemented within their organization, they need help in the form of well written, high-quality tutorials and examples. JBoss traditionally puts out first rate documentation in the form of user guides. Unfortunately, user guides alone are not enough as the authors can't accommodate every situation a user will come across when writing developer documentation in book form. Also, finding the answer to a specific problem requires careful reading on the part of the user if the solution is contained in a comprehensive user manual. Breaking individual topics into discreet chunks, recipes, makes it more likely the user will absorb the topic they're trying to learn.
The cookbook is a shortcut to understanding. One under-appreciated factor in Java's success was that Sun and various authors and community members documented best practices early on instead of letting users stumble through lessons on their own. Most programming professionals are paid to solve specific domain issues, such as creating tools for their industry (finance, medicine, commerce, etc). The more time they're spending learning a platform, the less time they're devoting to creating solutions to the problems they were hired to solve. Many professionals don't want to discover best practices on their own. They want to be told how to solve basic code wiring and plumbing issues so they can focus their energy on pleasing their customers. A cookbook format gives busy professionals authoritative lessons they can quickly apply to their applications with less effort than reading an entire user manual.
Each Recipe will be a minimal example and tutorial with the following traits:
The scope of a recipe must be small and demonstrate a single concept. Like most tutorials, it should contain text explaining the concept and example code. The author should get to the point as succinctly as possible.
Each example will have a full, buildable project which can be downloaded by the user so they can run it themselves, preferably in Maven. This is critical as when using web technologies, like Seam, the functionality often will be split across many files. For example, a persistence example will require a persistence.xml as well as at least two Java files. Having a universal project structure will make it trivial for the user to open the example in their IDE and figure out what the project is doing.
The author should make all efforts to keep the “signal-to-noise” ratio high. A great tutorial is one in which is only includes enough code to illustrate your point and not a line more. Throwing in unneeded configuration or lines of code has the potential to confuse users.
SCM and CI
Few things will turn off users faster than errors, so these tutorials need to be treated like production code. If you and I were writing a production application, we would demand version control and continuous integration. Why should these tutorials be any different?
Sample code should be downloaded from a Source Code Management system like Git or SVN. Giving users access to our version control not only provides transparency, but I believe it encourages participation.
Verified recipes should be built via Continuous Integration. This is actually negotiable, in my mind, as securing a CI for use by strangers may not be a trivial task. I certainly think projects from verified users could be trusted to have CI jobs, but concede that there may be security concerns I have not explored thoroughly enough.
The Hierarchical Cookbook
The cookbook should have of a hierarchical representation of topics, organized by broader to finer level of technologies. For example, a top level project like Weld would get its own cookbook. The cookbook would have a section on testing using TestNG. Inside the TestNG section, the cookbook would have a recipe for testing a Weld component using Arquillian. The hierarchical nature will allow a user interested in a topic to trivially find related examples. JavaAlamanc.com has done an excellent job organizing an index that makes it easy to find related tutorials or just browse the articles available.
JBoss alone cannot provide as many answers as the broader community can. Crowdsourcing also will lower the costs of maintaining the site and increase community participation. In order to balance cohesive organization and quality with comprehensive examples, the site should take submissions from users, but it should rely on trusted moderators to curate the table of contents
Verified Main Cookbook and Unverified Community Cookbooks:
In order to minimize bad tutorials (having errors, abuse and advertisements), bad practices, duplications, etc, the site will need trusted moderators, such as JBoss employees and screened volunteers.
When a user writes a recipe, it'll go into the unverified cookbook and will be searchable by users. In order to appear in the table of contents, a trusted moderator must promote it to the correct section. In order to make the moderator's job easier, the community can vote a recipe up if they want it to be put in the main index. They can also mark posts as abusive, erroneous, or a bad practice. We should make all efforts to make the site easy to use by casual users, including voting.
Feedback and Discussion:
Users should be able to provide feedback on recipes via a simple rating system.
Users should be able to rate if the recipe is:
- Correct: represents a best practice and all information conveyed is correct.
- Informative: is well-written and succeeds in explaining whatever it is trying to teach.
- Succinct: high signal-to-noise ratio.
There should be boolean flags to help moderation. Each flag will have a text box for the user explain why the recipe should be flagged:
- Abuses Policy: ads, offensive language, spam, etc.
- Has grammar or spelling errors.
- Has technical errors.
Each example should be linked to a forum topic or discussion page so users can point out errors or ask questions. If you present a tutorial and imply it is a best practice, it will surely be controversial. Giving users a forum to have questions answered will be very beneficial in both pleasing the community as well as helping the authors improve their recipe.
Hi Steven. What you are describing is what we call "quickstarts". At the moment these aren't very well publicised (we're waiting until JBoss EAP 6 Beta is available to make more noise about them), but you can check them out on github: https://github.com/jbossas/quickstart.
We don't have a great user facing home page for these right now - the placeholder is https://docs.jboss.org/author/display/AS71/Quickstarts. One of the tasks before we "launch" them is to get this homepage updated. Would you be interested in working on that? I can work with you on it. I don't know if confluence has the rating system you describe, you could investigate options for this. If we need a plugin, we can get it added to our instance.
We have focused much more to date on building up the "rules" for creating quickstarts, you'll find them if you follow the links from the homepage.
One thing we don't do is build these in Hudson, but I think adding this would be fine.
Sande Gilda, Burr Sutter and I are the moderators for this project.
I know it's slightly off the beaten path from what Pete is suggesting, but from what I've seen and could fairly easily envision being dobale is to have all of this stuff hosted in GitHub, which would provide us with a transparent location, and issue tracking. CI could very easily be done using OpenShift. Then for the site we could actually build up something with Awestruct that would use the README file or some other marker file for the entry into the system. The feedback system is something wouldn't be there but probably could be done similar to how diqus or intensedebate works. Then any time a new recipe is added we'd signal to the CI server to rebuild and push the new site. This would nearly be fully automated and take a lot of weight off whomever would be the moderator for recipies.
I'd love to help out!
I like the quickstarts. They're everything I've wanted in sample apps.
I checked out a few projects and like how their POMs are independent. One minor challenge with some project examples, from many open source projects, is that they have a complex POM hierarchy. These don't inherit multiple parents, so I can take this example, change the group and artifactId and start a project from it. I was very pleasantly surprised by that, kudos!
I think one thing that would make these really awesome is if there was a small tutorial for each of these in the form of a blog post or perhaps even something more succinct like you'd find on exampledepot.com
Not off topic at all Jason. I just registered the jboss-as-quickstart account and the quickstart domain with OpenShift express, and asked Matt Hicks (who is the OpenShift Express tech lead for those who don't know him) to up the limit on the apps deployable to 50, so that we can put all the quickstarts on that one account.
I also really like the idea of using OpenShift for the CI portion. We can put that on the same quickstart account. The only part that needs a bit of research and process is the automated deployment part. I've been using bash scripts extensively to automate tasks, so that could be a good way forward.
I'm happy to own this task (can't promise to address it immediately) unless anyone else wants to take it forward...
Yes, we felt it was critical to keep the POMs as simple as possible, and as close to user POMs as possible. That meant no inheritence at all.
Regarding tutorials, our plan is to keep these in the README.md, so that they are versioned with the project. Some quickstarts are better at this than others ;-) So this is something to improve on. If you want to file issues on github regarding what you do/don't like, we can work with the authors to improve them.
If we were to build up a project site, then we could link to these README.md and have them rendered as html...
Regarding how to build the project site, the only caveat is that for these quickstarts to be really valuable, they need to be deeply integrated into "the jboss experience" so we're limited to the tools we have at JBoss.org, at least for the initial home page.