Re: docs.fedoraproject.org front page suggestions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux