Java EE Cookbook idea
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.
Why? :
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.
The Details:
The Recipe
Each Recipe will be a minimal example and tutorial with the following traits:
Small Scope
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.
Downloadable Project
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.
Crowdsourcing maintenance:
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:
Feedback:
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.
Discussion
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.
