maliput / maliput/maliput_documentation
[Meta]Improve documentation
- Dominant language
- CMake
- Stars
- 1
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
### Objective
Modify/improve documentation to make it more user-friendly for new users, so its testing and adoption are easier.
https://maliput.readthedocs.io/en/latest/index.html
### Tasks
- [ ] Installation process: https://maliput.readthedocs.io/en/latest/installation.html
- Keep it simple: Guide people to install maliput and maliput_malidrive. Refer people to investigate other backends (via the maliput backends section.)
- Focus the getting started documentation to use maliput malidrive
- When building from source? Also use as example maliput malidrive. Otherwise we are pointing the people to install the entire maliput ecosystem just when they are trying to understand the tool.
- [x] Create maliput backends section: https://github.com/maliput/maliput_documentation/pull/146
- Comment about how maliput propose an API
- Comment the available maliput backends
- Comment about how to rely on maliput_sparse in order to create a maliput backend
- Maliput dragway and multilane aren’t being used and they work mostly as examples on how to build their own backends-
- [ ] The Getting Started page https://maliput.readthedocs.io/en/latest/getting_started.html
- The current information (the basics and advanced) is actually explaining concepts and showing the code on how you can use it. I think this section should be called `Concepts`
- I'd have a Getting Started that only guides you to create your own example and to be quite simple and straight forward.
- [ ] Modify tutorial section by applications
- Mention the applications that are offered by maliput_integration:
- Mention that some packages offer applications that are particular to their packages and list them here. (maliput malidrive apps.)
- [ ] Move all delphyne related packages (also drake vendor) into another section (like `Related Projects`). So we can dissociate them from maliput base stuff as they probably won't use delphyne.
- [ ] Create a separate section only for the `maliput_viz` tool so people use it as they investigate about maliput. Visualization aid is essential for understanding.
- [ ] Create an example on how OpenDRIVE maps are used via maliput_malidrive and how you can add more rule and semantic information into road network via maliput API.
- [ ] What's the use case? (For reference: Why using this over lanelet2 for example?)
- [ ] Documentation on the backends:
- For example. maliput_malidrive creates rules out of the xodr definition for indicating direction usage rules, vehicle supported for instance or even speed limit rules if available in the xodr definition. We should document the rules that are being automatically obtained from the underlying format. (Besides the yaml file that can be passed to the road network to load up custom rules)
Contributor guide
Research direction
Start with the linked installation and getting_started pages, then review the tutorial sections and the completed backends section, including pull request 146. Done means the remaining unchecked documentation goals are organized into a consistent, beginner-focused structure covering installation, examples, applications, related projects, visualization, use cases, and backend behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100