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
2. Link between sites and document only specifics to an ecosystem
Both of these have pros and cons: * duplicate content vs. linking between sources * everything on the same place vs. the need to access multiple sources * the need to automate the publication process * translate documentation sources between various formats * maintenance burden for the duplicate or fragmented content
Right now we have some documentation available here https://docs.centos.org/en-US/stream-contrib/contributing/source-git/ while the technical details live on https://packit.dev/source-git Is this fine or should we improve? The feedback we got so far was to unify it in a single place so I wanted to open up a discussion to hear more.
Thank you for your time, Tomas
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:
- 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.
- 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,
On Fri, Sep 24, 2021 at 2:35 PM Alain Reguera Delgado < alain.reguera@gmail.com> wrote:
- 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!
- 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!
Tomas
On 27/09/2021 16:49, Tomas Tomecek wrote: <snip>
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/ <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/ 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.
Wondering if we can combine with another proposal that we wanted to present for the SIGs : it all started from the Automotive SIG and initial request to provide a simple doc like the one we use for the infra doc (all based on mkdocs - https://www.mkdocs.org/) :
https://pagure.io/centos-infra/issue/458
So basically, that would be something like https://sigs.centos.org/<sig_name> and content being built from a git origin url (hosted wherever SIGs want, as long as it's public doc) and it would be rendered automatically
On Tue, 2021-09-28 at 13:39 +0200, Fabian Arrotin wrote:
Wondering if we can combine with another proposal that we wanted to present for the SIGs : it all started from the Automotive SIG and initial request to provide a simple doc like the one we use for the infra doc (all based on mkdocs - https://www.mkdocs.org/) :
https://pagure.io/centos-infra/issue/458
So basically, that would be something like https://sigs.centos.org/<sig_name> and content being built from a git origin url (hosted wherever SIGs want, as long as it's public doc) and it would be rendered automatically
/me subscribes to this issue. Hyperscale would love to have something like this as well for user-facing documentation.
Cheers Davide
On 9/28/21 07:39, Fabian Arrotin wrote:
On 27/09/2021 16:49, Tomas Tomecek wrote:
<snip> >> 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/ <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/ <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. > Wondering if we can combine with another proposal that we wanted to present for the SIGs : it all started from the Automotive SIG and initial request to provide a simple doc like the one we use for the infra doc (all based on mkdocs - https://www.mkdocs.org/) :
https://pagure.io/centos-infra/issue/458
So basically, that would be something like https://sigs.centos.org/<sig_name> and content being built from a git origin url (hosted wherever SIGs want, as long as it's public doc) and it would be rendered automatically
That sounds like a great plan.
Tomas,
What would the searchability be for a new contributor in order to find the information?
Can we do 'includes' of pages so that shared content is in one location and can be included to others? That way for example a Fedora page talks about Fedora and then includes the information that is relative to all projects and then could even return to Fedora specific information.
Thanks,
Amy
*Amy Marrich*
She/Her/Hers
Principal Technical Marketing Manager - Cloud Platforms
Red Hat, Inc https://www.redhat.com/
amy@redhat.com
Mobile: 954-818-0514
Slack: amarrich
IRC: spotz https://www.redhat.com/
On Fri, Sep 24, 2021 at 5:09 AM Tomas Tomecek ttomecek@redhat.com 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:
Have everything on the same site
Link between sites and document only specifics to an ecosystem
Both of these have pros and cons:
- duplicate content vs. linking between sources
- everything on the same place vs. the need to access multiple sources
- the need to automate the publication process
- translate documentation sources between various formats
- maintenance burden for the duplicate or fragmented content
Right now we have some documentation available here https://docs.centos.org/en-US/stream-contrib/contributing/source-git/ while the technical details live on https://packit.dev/source-git Is this fine or should we improve? The feedback we got so far was to unify it in a single place so I wanted to open up a discussion to hear more.
Thank you for your time, Tomas
CentOS-devel mailing list CentOS-devel@centos.org https://lists.centos.org/mailman/listinfo/centos-devel
Amy, thank you for your feedback!
On Fri, Sep 24, 2021 at 5:37 PM Amy Marrich amy@redhat.com wrote:
Tomas,
What would the searchability be for a new contributor in order to find the information?
That's a good question. I hope contributors will be able to use a table of content to get to the proper page they are looking for. In the end, search engines should also index the documentation site so that will be another way to find what you are looking for. Does this answer your question?
Can we do 'includes' of pages so that shared content is in one location and can be included to others? That way for example a Fedora page talks about Fedora and then includes the information that is relative to all projects and then could even return to Fedora specific information.
Amy, just to be clear, by "includes" do you mean to refer to the information by providing a link or directly include the text in such a documentation page?
I'm sorry my original post is so generic and hard to imagine - once we have concrete examples I believe it will be more clear what's the better approach.
Tomas
Tomas,
I was thinking include it in the page. So common information can have a single location but shared across multiple sites.
Thanks,
Amy
On Monday, September 27, 2021, Tomas Tomecek ttomecek@redhat.com wrote:
Amy, thank you for your feedback!
On Fri, Sep 24, 2021 at 5:37 PM Amy Marrich amy@redhat.com wrote:
Tomas,
What would the searchability be for a new contributor in order to find the information?
That's a good question. I hope contributors will be able to use a table of content to get to the proper page they are looking for. In the end, search engines should also index the documentation site so that will be another way to find what you are looking for. Does this answer your question?
Can we do 'includes' of pages so that shared content is in one location and can be included to others? That way for example a Fedora page talks about Fedora and then includes the information that is relative to all projects and then could even return to Fedora specific information.
Amy, just to be clear, by "includes" do you mean to refer to the information by providing a link or directly include the text in such a documentation page?
I'm sorry my original post is so generic and hard to imagine - once we have concrete examples I believe it will be more clear what's the better approach.
Tomas
-
Alain Reguera Delgado -
Amy Marrich -
Davide Cavalca -
Fabian Arrotin -
Rich Bowen -
Tomas Tomecek