Thoughts on revising tutorial, part 1, chapter 1

[edbratt]

I've re-read through part one of the tutorial and thought there are several aspects which we could consider revising. This issue captures my thoughts and could serve as a vehicle for further discussion and perhaps result in a revision roadmap or issue-epic for revising this introductory section

Generally, I believe the overview presented in this section is circa Java EE 5 or 6. There have been spot updates, but I don't think there has been any cohesive refresh to the overall platform description.

I would propose we consider adding more context that helps a reader understand Jakarta EE 9 and higher and also place it in today's computing environment landscape -- I would like to see brief mention of the following in the general overview text:

• Cloud based computing challenges
• Alternative container and orchestration services
• Some discussion about alternative platforms and components that helps the reader place EE in these various offerings

I would recommend we increase the introductory emphasis for

• CDI
• REST Web Services

We decrease the emphasis on

• EJB
• XML Web Services

We remove mention of

• CORBA and remote invocation
• Applet technology

Please comment if you have additional thoughts and/or add a reaction if you do or don't like the general direction I'm suggesting.

[cesarhernandezgt]

Hi @edbratt
I agree with your points about content.

About content:

• In my opinion, the section Jakarta EE 9 Platform Highlights can be expanded to make clear the implications of namespace change so developers (who the tutorial is aiming for) fully understand the migration needs and options of the existing application to the new namespace and maybe a new chapter can be created later to explicitly provide guidance on how to do the migration if the application server they use don't do the work under the hood.

• Section Jakarta EE Application Model can provide the relationship between the Jakarta EE version and Java Runtime to make clear the difference between compiler and runtime level.

About the tutorial design:

• I wonder if the approach of running the examples can be switched to use the embedded server (a maven plugin one) instead of requiring as the first option to have DB, IDE, and a server installation with a configured domain, Don't get me wrong, the sections about how to start, stop, and overall management for server, IDE, and DB is fine and may be useful to keep, but in today's context, is like if you go to spring boot tutorial and the first thing you see is how to configure, start, stop, deploy Tomcat. In my humble opinion, the success of the tutorials like the ones spring boot and other technologies are that they managed to reduce (abstract) the server configuration to keep the audience focused on the code itself and keep the deep server, IDE integration as a specific chapter (module) instead of being part of the prerequisites for all the tutorial examples.

• Another improvement can be to add the expected reading/execution time for each chapter and/or examples. I know this is relative to the person reading and executing the examples of a particular chapter, but having this will also provide guidance on potential chapters to be subdivided and help the readers to better choose the sections they want to dive in.

[kazumura]

It would be better to have some kind of migration and compatibility documents among the Java EE/Jakarta EE versions.
These may be the outside the scope of the tutorial.
But in practice, when migrating the existing Java EE application to the current Jakarta EE, most of developers need to these kind of information.

[anno1985]

Currently, the chapter is targeting both new and experienced enterprise developers:

Whether you are a new or experienced enterprise developer

Yet, it uses terms such as dependency injection and "XML deployment descriptors" without explaining them or at least pointing to a chapter/tutorial that does. Maybe that could be improved/avoided when the chapter is rewritten.