Lighten the Getting Started tutorial #6476

Tell us about your request

The Getting Started tutorial is accurate and teaches good patterns, but it's heavy for its main audience. It was reviewed from two reader perspectives: a Java student new to Vaadin, and a senior Spring Boot developer evaluating it.

• The student: would likely stall around Edit Details.
• The experienced developer: has no way to skip material aimed at beginners.

The quick fixes from that review are handled in #6475: Windows commands, restart reminders, the IntelliJ IDEA wording, the 25.3.2 note, and the version-bug heading. This issue covers the larger changes.

Step sizes

Code lines include the complete listing at the end of each step. The tutorial index says to expect 15 to 45 minutes per step. That doesn't hold for Edit Details or Add Data.

What to change

1. Split Edit Details. It introduces all of these at once:

   • an application service with @Service, @Validated, and @Transactional;
   • an Optional-returning API;
   • Bean Validation and binder validators;
   • an identifier provider to preserve the grid selection;
   • an error-handling design, Notification, and Confirm Dialog;
   • a versioned delete.

   Split it into two steps, for example "Save & Validate" and "Handle Errors & Delete".

2. Add a map to the tutorial index.

   • A table of what each step teaches, for example Binder in Show Details and Edit Details, and browserless tests in Add Tests. Readers see where they're going, and experienced developers can skip what they know.
   • A picture of what runs where: the browser, the server-side view, the application service, the repository, and the H2 database.
   • A list of the classes in the finished project.

3. Explain the Spring features the tutorial uses, briefly or with a link.

   • Constructor injection, in List Data. The only explanation is "Use constructor injection to get the repository instance". Nothing says that Spring creates the view and passes the repository to it.
   • @Service and transactions, in Edit Details, "Add an Application Service".
   • @Autowired, in Add Tests.

   A short "What Spring does here" note in List Data, and one sentence on what a transaction is, would be enough.

4. Define jargon where it first appears.

   • FDO is expanded in Show Details but only explained through a link.
   • JavaBean and JSpecify (Show Details) and domain primitives (Edit Details) aren't defined at all.

   Also move design rationale that a first-time reader can skip into collapsible "Why?" blocks:

   • the entity rationale in Show Details;
   • the BeanValidationBinder aside in "Validate the Form";
   • the REST comparison in Add Data;
   • flexbox sizing in List Data.

5. Make the functional style easier to follow. Optional, flatMap, method references, and ternaries appear together in Show Details and Deep Link. Explain Optional and flatMap once, or show a plain if/else version first.

6. Explain the two data classes.

   • ProductCatalogItem and ProductDetails map the same table, with a repository each. Show Details justifies the second class only with "you can't use ProductCatalogItem".
   • List Data says record fields "must match the column names", but productId maps to product_id, and the naming convention isn't explained.

7. Show full listings less often. Sort & Filter shows ProductCatalogView in full five times, counting the complete listing at the end. Show only the changed parts in the body.

8. Revisit the time estimate once the steps are rebalanced.

Related, outside the tutorial: Next Steps goes straight from the tutorial's in-memory H2 database to Flyway, PostgreSQL, and Testcontainers. A student-scale option, such as keeping the H2 data in a file, would help course projects.

If you think this issue is important, add a 👍 reaction to help the community and maintainers prioritize this issue.