Modernizing and Streamlining the Jakarta EE Tutorial

The tutorial has long been the face of Jakarta EE. Since the days of Java EE, before Jakarta EE even existed, the tutorial has been the main way for new people to learn about and potentially get involved with cloud native Java. 

But it’s overdue for a bit of a face lift. Though it’s been updated before, it is still in many ways a product of its time and could benefit from modernization. As one of the first and primary points of contact for new members of the Jakarta EE community, it’s important that there be as little friction and confusion as possible when using it. But first, a bit of background. 

Tutorial Is Critical Entry Point to Jakarta EE Ecosystem

From the beginning, the tutorial was meant to be a way to get basic information about Java EE, now Jakarta EE. If you wanted to learn about Jakarta REST  (formerly JAX-RS), or Servlets, or EJB or CDI, or JPA, this was the place to go. 

The key thing about Jakarta EE is that it consists of a set of specifications. So, without the tutorial, if you want to learn how to use a given specification you could either read the vendor documentation, find some articles or books written by third parties, or read the specifications themselves. 

Historically, this put a lot of pressure on vendors to produce a lot of documentation because the specifications themselves were very dense and hard to read, which is why third parties had to write articles and books about it (although the newer specifications are much better). So having a clear, easy-to-read, and comprehensible tutorial is very important to make sure people can easily enter the Jakarta EE ecosystem.

Current Focus on Jakarta EE 10

There have been a few changes made to the tutorial that are worth highlighting:

• Namespace changes
• Changes for new specification names
• Updated images
• Minor updates based on changes in Jakarta EE 8 and 9

As of now, the tutorial is up-to-date with changes made in Jakarta EE 8 and Jakarta EE 9. For the moment, we’re still focused on updating it to Jakarta EE 10, but with the upcoming Jakarta EE 11 release, we will be making those updates later as well. 

Focus on Structure and Content Refresh

The major goal of this latest update is twofold. Overall, it’s a refresh. That means that, among other things, there’ll be some aesthetic changes to the tutorial to give it the look and feel of a modern piece of documentation. But we’re also focusing on refreshing the structure of the tutorial, as well as the actual content itself. 

The structural changes we’re working on are built off the AsciiDoc chassis. Right now, the whole tutorial is built into one big HTML file, which is very easy to search but not so easy to navigate. What we’re doing is migrating it to a framework which uses AsciiDoc called Antora, and integrates other features. The goal here is to make the documentation more modular and more easily searched and sifted through, and give us the ability to pull in content from other repositories. In the future, this foundation could allow us to integrate individual specifications and other documentation within the same structure, which would make this a one-stop-shop for Jakarta EE documentation.

The content refresh also has two parts. First is to just bring all the content up to date with all the changes in Jakarta EE 10 so we’re ready for Jakarta EE 11. But while we’re at it, we want to improve the content itself. As mentioned earlier, the tutorial is still somewhat a product of its time, and it’s written in a very old-school way: it’s very formal and explains a lot of basic concepts that it really doesn’t need to. So, while we’re tidying up the content, we’re also going to clear out some of the fluff and focus only on the information people really need. If you want more details, you can find them in the specifications themselves.

Secondly, we’re also doing some trimming. The tutorial is quite large right now, and it refers to a lot of old technologies that aren’t used very much these days. So, we’re in the process of de-emphasizing those old technologies. You’ll still be able to find them in the tutorial, but they’re not going to be a main part of it. 

We also took this opportunity to move the tutorial examples into the Jakarta EE Examples project, which includes quite a few simple, focused examples. In addition, we’ll be updating or rewriting examples, because some of them are outdated and aren’t easy to run. With both the tutorial and existing examples in one repository, you can easily find useful examples whenever you go looking. 

A New Jakarta EE Project

The tutorial used to be part of the Jakarta EE Platform project, which manages the platform as a whole. But to support this work and grow the documentation footprint of Jakarta EE going forward, we have established a new project for the tutorial and future documentation called Eclipse Documentation for Jakarta EE. 

Target Release by End of Year

Our goal is to complete the initial phase of this work by the end of the year. In the meantime, feedback from the community would be greatly appreciated. Basically, we want to make sure the tutorial is achieving what we’d hoped: that it’s more intuitive to use and that it is easier to navigate and find what you’re looking for than it was.

If you’d like to leave us feedback or get involved, please visit our repo on GitHub.