Feedback on some Jakarta EE tutorial and FirstCup work

[Guillermo González de Agüero]

Hi everyone,

I've done some work on the Jakarta EE documentation:

1. Tutorial: converted to plain AsciiDoc without JBake. PR - Preview
2. Tutorial: splited content into standalone guides (based on previous bullet). PR - Preview
3. First Cup: converted to plain AsciiDoc without JBake. PR - Preview

It's particularly the second bullet of my work that I need feedback on. I know some people find the tutorial daunting due to its length, and also go away after seeing how much it promotes JSF and EJB. The current format of the tutorial is also not very user friendly (which is hopefully already fixed by converting it to a single page content).

You can see the current rendered versions on:

• Tutorial: https://eclipse-ee4j.github.io/jakartaee-tutorial/toc.html
• First Cup: https://eclipse-ee4j.github.io/jakartaee-firstcup/toc.html

My version, available at http://www.ggam.eu/jakartaee-tutorial/guides/ groups technologies into guides and moves JSF, SOAP and EJB to a separated "classic architecture" section. EAR packaging and Client Application Containers are other concepts I think should better be moved to less prominent places. I haven't touched the contents for this, only created new pages for the guides (see https://github.com/ggam/jakartaee-tutorial/compare/jbakeless...ggam:split-guides for specific changes)

It's a POC (links and images doesn't work), but I'd like to get some early feedback on the idea very going far. I know everybody is busy working on Jakarta EE 9 but for that same reason I think this is the right time to move the documentation forward so we get a revamped version by the time 9 is released.

Regards,

Guillermo González de Agüero

[Guillermo González de Agüero]

Adding Jakarta Community list which is more suitable than the WG one.

[Reza Rahman]

The primary problem with the Tutorial is the pedantic style related to its age. The TOC is definitely the place to start fixing that but in truth the content itself needs to be evolved. Many of the concepts explained just don't need to be explained in such detail at all and is more the realm of specification documents that a guide aimed at new users. Some content can just be dropped outright as it is not necessary to meet the 80% use case.

Overall I would say the restructured TOC looks right. I would say you could even move WebSocket to advanced concepts. It has been many years since Java EE 7 and I have not really seen significant uptake in the field. EJB is a difficult one. I completely understand the desire to move it out of the way. The problem is that until there are replacements, there is some very important basic functionality in there such as MDB, @RolesAllowed, @Asyncronous and @Schedule.  What I suggest is creating an "EJB Basics" chapter and keep it in the primary section. An "EJB Advanced" section can be kept in the place you have it now to cover things like stateful beans. The other thing to think about is ordering. It is best to try to create a learning path for a beginner. For example, REST, Persistence and Transactions would probably come before things like JSON, Bean Validation and Security.

Hope that helps. I certainly could help you more directly but I really feel like the priorities for me personally need to be Jakarta EE 9, Jakarta EE 10 and the Jakarta EE Ambassadors. Maybe other people with significant prior authoring experience can step up? In particular Manning editors do a good job of working with Manning authors to aim for simplicity and creating learning paths.

Reza Rahman
Jakarta EE Ambassador, Author, Speaker, Blogger

Please note views expressed here are my own as an individual community member and do not reflect the views of my employer.

_______________________________________________
jakarta.ee-community mailing list
jakarta.ee...@eclipse.org
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-community

[Guillermo González de Agüero]

Hi,

Thanks Reza for your comments. I agree with your perception that the content is heavy reading, but we need to start somewhere to enable contributions, specially from the community. The document was very difficult to maintain and I felt it was difficult anyone would contribute to it.

Regarding EJB and the likes, my idea is that the documentation must be organized by use cases and not than by technologies. @RolesAllowed should be explained in the Security guide; @Asynchronous and @Schedule in the Concurrency guide. As a user, I don't really care whether I'm using something called "Concurrency Utilities" or "Enterprise Jakarta Beans", I just want to make some asynchronous invocation and I expect to find that functionality on the Concurrency guide.

I'll reorder the items you mentioned, thanks for the suggestion!

Regards,

Guillermo González de Agüero

--
You received this message because you are subscribed to the Google Groups "Jakarta EE Ambassadors" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jakartaee-ambass...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jakartaee-ambassadors/2768fc0b-391d-0bd6-0ada-a79c207ddb45%40lycos.com.

[Arjan Tijms]

Hi Guillermo,

Thanks for all the hard work you're putting into this, very nice! :)

You might have expected me pushing a little back against the notion of Faces (JSF) being moved to a classic architecture, although as I mentioned in my Jakarta Livestream presentation from last year I'm of course aware javascript client UIs with a REST backend are used an estimated 10x more at least (just in the Java world).

The reason is that as far as I know SOAP and EJB are not further developed anymore, i.e. no new features are planned for it. With Faces this is almost the opposite, we have a large list of features and enhancements planned for 4.x and beyond. Also, serverside rendering has come into vogue again (see same presentation mentioned above).

Anyway, don't let this little pushback stand in the way of your work ;)

One thing I found greatly confusing in the tutorial, especially for newer users, is the fact that at quite a few places it doesn't really make a distinction between Jakarta EE concepts, and GlassFish concepts. You see this especially in the security chapters, where group mapping and realms are discussed as-if they were Jakarta EE concepts. I think it's currently a bit better as in the earliest versions, but see e.g. https://eclipse-ee4j.github.io/jakartaee-tutorial/security-intro005.html#BNBXJ

Hope this helps, keep up the good work!

[Guillermo González de Agüero]

Hi Arjan,

Yes, I expected your comments about Faces! Let me clarify that I intentionally stated "Traditional" and not "Legacy" architecture as I think those technologies are valid choices, just that we don't want to promote it as *the Java EE solution* anymore. The first step towards that is separating the contents into guides, so everyone can decide which parts they are interested in.

I grouped the concepts somewhat arbitrarily, but you are right it seems unfair to move it as a non recommended approach when it's still being developed. It can be categorized as "Server Side Templating" along with JSP (which btw, is'nt documented in the tutorial). 

Very good point about the mix of Jakarta EE and GlassFish concepts. While fixing the tutorial examples (https://github.com/eclipse-ee4j/jakartaee-tutorial-examples/pull/25) I found there are a lot of places where GF deployment descriptors or commands are used. Maybe those examples need to be put into specific "GlassFish example for XXX" guides. I'll try to have a look at it.

Thanks for the feedback!

[Cesar Hernandez]

Hi,

Thanks, Guillermo for the detail PR's and really useful preview sites.

About: http://www.ggam.eu/jakartaee-tutorial/ +1, greater work into the conversion.

About: http://www.ggam.eu/jakartaee-tutorial/guides/

This is interesting because the current categories (Introduction, core, advance, and traditional) can be subjective to the need of a particular reader.

I like Reza's proposal on creating the categories order as "REST, Persistence and Transactions". 

By taking a look at the [1] JakartaEE developer survey, it's clear that cloud-native architectures are #1 requirement and this generally requires REST, Jsonb, persistence and Security. If I had to propose a set of categories, I would create categories base on new users needs like:

• Integration
• Persistence
• Security
• etc.

[1]https://jakarta.ee/documents/insights/2019-jakarta-ee-developer-survey.pdf

Atentamente:
César Hernández.