The quickstarts page is difficult to follow and contains outdated code

[tomashauser]

I tried following the quarkus-quickstart without the underlying code so that I could initially read through it, try out the steps, and then review the "solution." However, this proved challenging, as the article introduces pieces of code that use outdated APIs, and there are instances of code appearing without context. I tracked the issues I encountered so that the quickstart article can be improved. I also have a few suggestions.

1. In this section, you can directly use a URL with preselected options:

   https://code.quarkus.io/?a=timefold-solver-quickstart&j=17&e=resteasy&e=resteasy-jackson&e=ai.timefold.solver%3Atimefold-solver-quarkus-jackson&e=ai.timefold.solver%3Atimefold-solver-quarkus
   

   This saves users from manually selecting options.

2. In multiline commands using a backward slash (\), add a note for Windows users to place the command on a single line if they use CMD.

3. In this section, it says:
   "Planning value ranges need to be countable, meaning there needs to be a finite number of possible planning values."
   This is not technically correct, as countability does not imply finiteness (for example, the set of natural numbers is countable but infinite). I would suggest saying that they need to come from a finite collection.

4. When reaching this step: Create the Solver Service, the tutorial starts using javax.ws.rs, but newer versions of Quarkus will rightly complain that jakarta imports (e.g., jakarta.inject.Inject, jakarta.ws.rs.POST, jakarta.ws.rs.Path) should be used.

5. In this section, you call TimetableConstraintProvider::roomConflict, but in this earlier section, it was made a private method.

6. The code from the previous point is also invalid, as the room variable is named ROOM, not ROOM1 as referenced in the roomConflict test. Additionally, the new Lesson object calls a constructor that wasn't defined in the Lesson class snippet.

7. In Test the Solver, jakarta.inject is correctly used, but the constraint test before it still uses javax imports, which Quarkus does not accept.

8. The test in this section uses org.awaitility, which was not listed in the dependency list at the beginning of the tutorial.

9. Finally, the test in Test the Solver calls .getSolverStatus, which is not part of the Timetable definition. The user following this quickstart has no way of knowing the contents without downloading the quickstart project files. Additionally, there is mention of demo data that isn't explained elsewhere.

[triceo]

Thanks for the notes, @tomashauser!
Did you consider submitting a PR to fix the doc?

[tomashauser]

I'll leave it like this for now. The doc need a more thorough rework and, possibly, a discussion preceeding it, hence why I opened up a thread. Feel free to use these notes :)

[TomCools]

Created an issue for this and picked up the first pieces. Have a few discussion points on a wider conceptual level. #1202

[TomCools]

The ticket already fixed some things, but while working on this I found some other inconsistencies. Will be picking those up with a future merge request.