Matthew Miller <mattdm@xxxxxxxxxxxxxxxxx> wrote: ... > > That being said -- not sure Antora the way we are currently using it > > is meeting our needs either. > > Are there any other options worth exploring? I have experience of Sphinx, and I've tested mkdocs and docsify relatively recently. I'm also aware of Gitbook, mdbook, and some custom solutions I've seen, including our own developer portal. Selecting a tool obviously depends on what the goals and requirements are, and it would be interesting to know why Antora was selected previously. There are some things that I think we obviously want, like search and ease of contribution. But there are also some more open questions: - Style of navigation and site organisation. Book-like docs tools are fairly common (see Sphinx, Gitbook, mkbook, etc). However, if we want docs with a more granular structure, we're likely looking at some kind of CMS or a custom solution. - Translations - always a thorny question. They often sound great in principle but are harder to do in practice - you need the translations to have a high level of coverage and to be actively maintained in order to be useful. - What kind of resources do we have to style and maintain the site? (I am assuming we want something that isn't a vast amount of work to look good, and to keep looking good?) - One site or many? And how to link them together. But for me, the biggest question is how to create a platform that fosters organic community participation. Honestly, I'm not sure what the answer is there. I see some successes in more tightly defined projects, but for large scale projects like Fedora it is more challenging. > I mean, we could always use > https://meta.discourse.org/t/discourse-docs-documentation-management-plugin/130172 The main question I'd ask there is the whether contributors would update posts they didn't originally author. > ... it'd mean switching to Markdown, which I actually don't think > would be the end of the world, but we've got a lot of Sunk Cost there.) I'd be interested to know what are those Sunk Costs are... Allan _______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@xxxxxxxxxxxxxxxxxxxxxxx Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
