Dev Content Review

[gkwan-ibm]

General comment:

• The README likes a lab/exercise. It may be OK if there is an instructor to guide and explain to the readers/users. The purpose of the guides is to let developers for self-learning, so the instruction should be clear and should not let them guess.

Suggestions:

• add maven wrapper to the finish and start directories
  • get the maven wrapper from any other guide
• remove the .vscode directory
• What you’ll learn
  • suggest to have a paragraph to tell the main purpose of using Jakarta Data (why use it?)
  • suggest adding doc link on
    • Jakarta Data Query Language
    • data access specification
• Try what you’ll build
  • replace include::{common-includes}/twyb-intro.adoc[] to include::{common-includes}/twyb-intro-mvnw.adoc[]
  • replace all [role='no-copy'] to [role="no-copy"] or [source, role="no_copy"]
    • the output boxes should not be green boxes with copy button
    • they should be in gray boxes without copy button
    • also, make sure the columns are aligned correctly
• Creating an Entity and Repository
  • "Creating an Entity and Repository" -> "Creating an entity and repository"
  • replace include::{common-includes}/devmode-lmp33-start.adoc[] to include::{common-includes}/devmode-mvnw-start.adoc[]
  • Users will have no idea what to do for the code Package p1 = new Package(1, 10f, 20f, 10f, "Rochester");...
    • follow the guide practice
      • a description of what going to achieve
      • replace or create the file
      • explain the detail of the changes with hotspots that are made
• Query by Method Name
  • "Query by Method Name" -> "Querying by method name"
  • follow the guide practice as above
• Using Annotations
  • "Using Annotations" -> "Annotating " (a better title)
  • The beginning of the section needs a description of the purpose of this section
  • each subsection title should be consistence
  • each subsection content should follow the guide practice as above
• Sort, Limit, and Pagination
  • "Sort, Limit, and Pagination" -> "Sorting, limiting, and paging data" or a better title
  • can improve each subsection title instead of using a word
  • each subsection content should follow the guide practice as above
• The Query Annotation
  • "The Query Annotation" -> a better title
  • the content should follow the guide practice as above
• Where to next?
  • no need to have this section and move the message to the above section
  • if want to keep this section, "Where to next?" -> "Next steps", and move this section after the Testing the application section
• There is no instruction for users to try out the application in each section or after all changes
  • if need to do after all changes, add a Running the application section at this
• It is a guide practice to have a Testing the application section
  • if want to explain the test, do it like this
  • otherwise, like this

[gkwan-ibm]

@lauracowen fyi, for you to follow up this new guide