[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
Re: [jakarta.ee-community] Feedback on some Jakarta EE tutorial and FirstCup work
|
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.
Hi everyone,
I've done some work on the Jakarta EE documentation:
- Tutorial: converted to plain AsciiDoc without JBake.
PR - Preview
- Tutorial: splited content into standalone guides
(based on previous bullet). PR - Preview
- 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:
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