idea: hosting community project docs under a single location
ssbarnea opened this issue · comments
Currently most community projects have their own websites, likely using RTD and their own themes.
The only exception I am aware of is ansible-lint which is nicely hosted under docs.ansible.com but the publishing process went broken and remained broken for more than an year. Mainly the project docs are out of sync with the project itself.
As I am aware of the sensitivity regarding what gets published to docs.ansible.com, I can understand that Ansible core team wants to assure that goes there is properly vetted. This is a bit of a conflict with the needs of the community projects, which may need or want to release docs at their own cadence, and more important not to depend on others regarding doc publishing.
A: subfolder under docs.ansible.com
- maximum visibility
- easy search (make use of same search engine)
- cannot use RTD build process as we would need our internal publishing job to update production
B: subdomain like community.ansible.com
- good visibility, makes it clearly visible it is community driven
- still indexable and we could make results visible from docs searches
- we can make use of RTD subproject feature
- can use RTD custom domain feature to host all community docs, even disable advertising, with minor costs. If we decide to go DIY we can do it without affecting the user-experience
- Using RTD brings serious benefits, like being able to preview the pull-request builded docs, making much easier to review changes made to them.
C: each project with its own site (current)
- no search across projects
- much harder to distinguish between projects under community umbrella and random projects from internet
- documentation theming will obviously differ a lot between projects, affecting now only browsing but also maintenance
- prevents us from analizing how community documentation is displayed, consumed or to make more holistic improvements.
Looks like everyone's going for option C for now.