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

Fri Sep 24 12:35:22 UTC 2021
Alain Reguera Delgado <alain.reguera at gmail.com>

Hello Tomas,

On Fri, 2021-09-24 at 12:09 +0200, Tomas Tomecek wrote:
> Hello, we're interested in hearing your feedback, the CentOS community,
> as well as my Red Hat colleagues.
> 
> Within our team (packit, context - source-git repos and workflow) we've
> recently discussed what would be the preferred way of structuring
> documentation for the source-git workflow. The thing is that the
> workflow would be available in Fedora, CentOS Stream (and transitively
> RHEL) while having some common documentation hosted in our project's
> documentation. That causes fragmentation and the need to link between
> various sources.
> 
> I'd like to hear what are your preferences:
> 
> 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.

> 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.


Best regards,
-- 
Alain Reguera Delgado <alain.reguera at gmail.com>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <http://lists.centos.org/pipermail/centos-devel/attachments/20210924/994e2cd1/attachment-0005.sig>