Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakarta.ee-community] [jakartaee-ambassadors] Re: Feedback on some Jakarta EE tutorial and FirstCup work
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

On Sun, Apr 26, 2020 at 8:53 PM Reza Rahman <reza_rahman@xxxxxxxxx> wrote:

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.

On 4/26/2020 12:18 PM, Guillermo González de Agüero wrote:
Adding Jakarta Community list which is more suitable than the WG one.

On Sun, Apr 26, 2020 at 6:15 PM Guillermo González de Agüero <z06.guillermo@xxxxxxxxx> wrote:
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).

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


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

--
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-ambassadors+unsubscribe@xxxxxxxxxxxxxxxx.
To view this discussion on the web visit https://groups.google.com/d/msgid/jakartaee-ambassadors/2768fc0b-391d-0bd6-0ada-a79c207ddb45%40lycos.com.

Back to the top