[CentOS-devel] Contributor documentation: to link between sites or all-in-one?

Mon Sep 27 14:49:45 UTC 2021
Tomas Tomecek <ttomecek at redhat.com>

On Fri, Sep 24, 2021 at 2:35 PM Alain Reguera Delgado <
alain.reguera at gmail.com> wrote:

> > 1. Have everything on the same site
> If the workflow is exactly the same for all distributions, I would go
> for option number one, a single documentation site and all references
> would point to it. There would be no distinction regarding the
> distribution itself. The site would document a common workflow that
> runs on all of them.

The workflow won't be the same since every ecosystem is using different
services and guidelines right now (e.g. Fedora has pagure, bodhi, community
maintainers while CentOS uses gitlab.com, pagure, custom composing, build
mirroring, strict change gating, Red Hat maintainers). I guess that's
making the decision easy now, thanks for a good pointer!

> > 2. Link between sites and document only specifics to an ecosystem
> If the workflow may vary among distributions, I would go for option
> number two, individual documentation sites for each distribution-
> specific workflow and would try to reuse all that is possible to reuse
> among them. In this case, each distribution-specific workflow site will
> have its own documentation reference. The way of reusing content among
> different distribution-specific workflow documentation sites could be
> addressed by pulling the appropriate git repos. Antora
> (https://docs.antora.org/) seems to be handy for such scenario.

Thanks for the tip! Antora looks like an interesting project and a good
fit, we'll definitely check it out more closely. I was looking at pandoc (
https://pandoc.org/ ) in the meantime.

You are right that we'll need to create documentation for every ecosystem
to describe the specific workflow. Once we have that we can try pulling the
shared content or link to it and decide what's better. I guess I'll make
another thread in future when we have a concrete proposal with actual
documents instead of just an abstract idea.

Thank you, Alain, for those great suggestions!

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.centos.org/pipermail/centos-devel/attachments/20210927/c6fe78ca/attachment-0005.html>