Documentation link and a few documentation improvement suggestions

[giovannifereoli]

Hi! Maybe it’s just me, but I wasn’t able to find the documentation link in the README.

• It might be helpful to add:

https://jso.dev/JSOSolvers.jl/stable/

I also had a few small suggestions regarding the documentation:

• There’s currently no explicit Statement of Need. Even a couple of sentences summarizing the purpose and motivation of the package (based on the papers) would help new users understand the scope.
• The examples in the Solvers section are useful, but it might be even better to have a dedicated Examples section with a couple of longer scripts - one for bounded and one for unbounded problems, possibly with plots or more complete workflows.
• Installation is easy (pkg> add JSOSolvers), but it could still be helpful to state it explicitly in the docs for completeness.
• I don’t see any community guidelines (e.g., contributing guidelines or a code of conduct).
• Could you clarify how the automated tests are organized? In particular, is there a test suite included in the repository, or are there documented manual steps for verifying the software’s functionality?
• Add a short note with the list of dependencies and how they’re managed

Thanks again for all the great work!

[giovannifereoli]

For the examples section, you could simply copy and paste from:
https://jso.dev/tutorials/introduction-to-jsosolvers/#title

[tmigot]

Thanks for the comments @giovannifereoli

The link to badge is accessible from the reamde's badges:

Regarding longer examples, the index.md page point to https://jso.dev/tutorials/ (select the badge JSOSolvers.jl) for more concrete tutorials. They were moved to a centralized place as they can serve as tutorials for several packages. I found copy-pasting from those harder to maintain, but if you think that's more appropriate in this package, why not.

For the other comments I opened a PR #333. The community guidelines is essentially the Bug reports and discussions that you can see in the readme. I also added it to the docs main page in the PR.

[giovannifereoli]

Not everyone realizes the badge is clickable, so it might help to mention that somewhere - maybe a short note in the README or in the description bar on the upper right?

From a navigation standpoint, I’d also like an Examples page in the left-hand docs sidebar (next to Solvers / Internals / Functions). Even a lightweight entry that simply says “Maintaining full examples here is difficult - please refer to the following examples: ” would make them much easier to find I believe

[giovannifereoli]

Thanks for the PR!

[giovannifereoli]

Heads up - I’m adding an item to the checklist above regarding automated testing!

[tmigot]

Regarding tests, there is a CI running. You can see the results here:
https://github.com/JuliaSmoothOptimizers/JSOSolvers.jl/actions/workflows/ci.yml
or in the ongoing pull request. We also check wether packages within JuliaSmoothOptimizers that rely on this package are breaking.

The unit tests are in the folder test as standard for Julia packages. Moreover, the codecov badge in the reamde gives you a code coverage score regarding the test, here it's 89% (clicking on the badge gives you detailed information).

[giovannifereoli]

I mean, I think you should put something about the automated testing in the docs too!

[giovannifereoli]

Also, could you add a short note with the list of dependencies and how they’re managed?

[tmigot]

Are these information (automating testing and dependencies) useful for potential users ? I am a bit worried this is information beyond the purpose of the package documentation and don't want new users to be lost in implementation "details".

[giovannifereoli]

I wouldn’t normally think to include those details in the documentation either, but I understand they can be important for contributors. I’m following the JOSS checklist, which asks for this information to be present… Maybe @nkrusch / other reviewers can weigh in on what they prefer?

[nkrusch]

Hi!

There are quite a few different topics going on in this one issue. I will offer some general guidance, mostly in light of JOSS criteria.

• For dependencies: The documentation should explain the dependencies that are necessary for the user to exercise the software.
• For testing: The software should have tests, and the documentation should explain how to execute the tests. It would be ideal to have those tests run automatically, but this is not a strict requirement by how the JOSS criteria is worded.

Both aspects are generally useful—to the software maintainers and users—to enhance the usability and maintenance of the software over time.

In my personal experience, going too deep into detail in dependency documentation can become an unsustainable maintenance overhead, especially for a small development team. I would advice caution around too detailed docs.

Finally, regarding collaborators and guidelines. The JOSS expectation is that such a guide is included in the repository. It has practical utility in streamlining the experience and expectations for outside collaborators. I would encourage to consider these guidelines as a "living" document. In other words, rather than guessing contributors needs, improve the guidelines based on issues raised by contributors as you go along.

[tmigot]

Thanks for the clarification @nkrusch ! I added instructions to run the unit tests in the doc (which is essentially to do ] test).

For the dependencies, I am indeed a bit unsure what additional information would be useful to add. As is standard in the Julia ecosystem, the package includes a Project.toml file that declares all dependencies and version compatibility constraints. A typical user does not need to install or manage these manually—running Pkg.add("JSOSolvers") and then using JSOSolvers automatically installs the appropriate versions of all required packages.

The JOSS paper already provides some motivation for the key dependencies, but we can certainly clarify this point in the documentation. For example, we could add a short section explaining that dependencies are managed through Project.toml and automatically handled by Julia’s package manager, with no manual action needed from the user.

We want to avoid listing or duplicating all dependencies in the documentation, as this would introduce unnecessary maintenance overhead and risk becoming outdated, but we are happy to add a concise explanation of how dependencies are handled in Julia and by the package.

[giovannifereoli]

I agree with you - this works well on my side too. The other reviewers can always suggest alternatives if they prefer something different, so let’s move forward with this!