Matthew Miller mattdm@fedoraproject.org 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/...
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