POMDPs.jl
POMDPs.jl copied to clipboard
JuliaPOMDP
The documentation is scattered
Even if the ecosystem is split into multiple packages I think the documentation should be centralized. It is often hard for newcomers to discover all the packages of the ecosystem. Examples:
- users implement their own simulation utilities before knowing that POMDPSimulators.jl exists
- users' entrypoint to the ecosystem might be from a solver, and they don't realize that POMDPs.jl should be the main entrypoint.
- POMDPExamples.jl and QuickStartPOMDP should feature in the POMDPs.jl documentation in the Getting Started.
- Related to #290, users often don't realize they actually need a lot of different packages to do what they want
- To find about a utility they have to know the existence of the package (e.g. POMDPModelTools) which not always obvious
Maybe the main POMDPs.jl page should have a section on the whole ecosystem linking to all the other documentations pages.
Agreed. I think we could improve this a lot! I think #290 would help this a lot, but I am not sure how to evaluate all of the difficulties that would come with that.
Regardless of the answer to the above question, I like the idea of putting more in the POMDPs.jl documentation. Now, with better Documenter doctests, I thing we should move the things from POMDPExamples into it. The concepts here are helpful for organization: https://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/ Reference docs should probably be as near to the code as possible, but tutorials and explanations should probably go in a central place.
It would definitely make sense to have a tutorial section where we could put all the examples. We have used Literate.jl here https://sisl.github.io/AutomotiveSimulator.jl/dev/tutorials/straight_roadway/ . It was not too painful as far as I remember.
The docs folder can have a separate Project.toml so it might be ok to have some dependencies on the solvers in there.
Definitely agree with @MaximeBouton.
For example, the defining (PO)MDPs could use some minor restructuring. It would be helpful to provide and overview at the beginning before delving into each one:
But overall, Julia POMDPs is great!
