Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://hackmd.io/@bookwar/centos-docs-layout
The link has more details but in short we need three categories of content:
* User Documentation: everything about installing and administering the CentOS system. Large guides go here, as well as small Knowledge Base articles.
* Project Documentation: All about processes and policies of the CentOS Project.
* SIGs documentation: Documentation subtrees maintained by each Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide (https://sigs.centos.org/guide/) belongs to the "Project Documentation" section in this hierarchy.
Each top-level item is then expanded to more sub-levels.
For many of the items mentioned in the proposal we do not have the content written yet. But if we agree on the layout, we can start by rearranging existing documents to fit the hierarchy.
Then we will be able to use the proposed map for any new content, which we add in the future.
On Wed, 2023-09-06 at 15:47 +0200, Aleksandra Fedorova wrote:
Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://urldefense.proofpoint.com/v2/url?u=https-3A__hackmd.io_-40bookwar_ce...
Awesome!
The link has more details but in short we need three categories of content:
* User Documentation: everything about installing and administering the CentOS system. Large guides go here, as well as small Knowledge Base articles.
* Project Documentation: All about processes and policies of the CentOS Project.
* SIGs documentation: Documentation subtrees maintained by each Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide ( https://urldefense.proofpoint.com/v2/url?u=https-3A__sigs.centos.org_g uide_&d=DwICAg&c=gRgGjJ3BkIsb5y6s49QqsA&r=OAMtP0DWou0nlXG7Kmxo2enjXJf wb1DXS9fwcaESuTE&m=0PgBUx5nfN4daWVydpBBK3- Jz5riNkYMnH2ISioaTzo4P7zh1NaIi3NDyaDs3bC0&s=AMs-BexBbhfm2hQZtl0d- F8nOeJ4UvMlDWIlofoPVWI&e= ) belongs to the "Project Documentation" section in this hierarchy.
Each top-level item is then expanded to more sub-levels.
For many of the items mentioned in the proposal we do not have the content written yet. But if we agree on the layout, we can start by rearranging existing documents to fit the hierarchy.
Then we will be able to use the proposed map for any new content, which we add in the future.
On 06/09/2023 15:47, Aleksandra Fedorova wrote:
Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://hackmd.io/@bookwar/centos-docs-layout
The link has more details but in short we need three categories of content:
* User Documentation: everything about installing and administering the CentOS system. Large guides go here, as well as small Knowledge Base articles.
* Project Documentation: All about processes and policies of the CentOS Project.
* SIGs documentation: Documentation subtrees maintained by each Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide (https://sigs.centos.org/guide/) belongs to the "Project Documentation" section in this hierarchy.
These ones (SIGs docs) already exist and are all rendered via mkdocs (from various git repositories) and so already under https://sigs.centos.org so no need to change the existing (and working) workflow :-)
FWIW, just waiting on Shaun to turn wiki into read-only static html files (we have a PoC and just need a "go" from Docs-SIG (see https://pagure.io/centos-infra/issue/1245) so content will be available (and stored in a git repo itself)
Each top-level item is then expanded to more sub-levels.
For many of the items mentioned in the proposal we do not have the content written yet. But if we agree on the layout, we can start by rearranging existing documents to fit the hierarchy.
Then we will be able to use the proposed map for any new content, which we add in the future.
On 9/6/23 16:48, Fabian Arrotin wrote:
On 06/09/2023 15:47, Aleksandra Fedorova wrote:
Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://hackmd.io/@bookwar/centos-docs-layout
The link has more details but in short we need three categories of content:
* User Documentation: everything about installing and administering the CentOS system. Large guides go here, as well as small Knowledge Base articles.
* Project Documentation: All about processes and policies of the CentOS Project.
* SIGs documentation: Documentation subtrees maintained by each Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide (https://sigs.centos.org/guide/) belongs to the "Project Documentation" section in this hierarchy.
These ones (SIGs docs) already exist and are all rendered via mkdocs (from various git repositories) and so already under https://sigs.centos.org so no need to change the existing (and working) workflow :-)
Yes, I forgot to say it explicitly:
I do not propose to put all docs into one repository. Or even to use the same tooling. Existing guides should stay where the are.
The idea is that we should have a defined hierarchy and a path how to get to the SIG Guide from the top page on docs.centos.org. And it is perfectly fine if following that path you use an external link and land on a different site built by a different tool.
So the *link* to the SIG Guide will be in the Project Documentation section on doc.centos.org.
Same for other parts of the documentation:
For example for SIG docs: there should be a section on the docs.centos.org which links to a specific SIG doc entry. This could be link to a repo with antora source, or it could be an external link to GitLab Pages site using hugo static generator. Or to mkdocs. Whatever people want to use for this particular part of the documentation.
FWIW, just waiting on Shaun to turn wiki into read-only static html files (we have a PoC and just need a "go" from Docs-SIG (see https://pagure.io/centos-infra/issue/1245) so content will be available (and stored in a git repo itself)
Each top-level item is then expanded to more sub-levels.
For many of the items mentioned in the proposal we do not have the content written yet. But if we agree on the layout, we can start by rearranging existing documents to fit the hierarchy.
Then we will be able to use the proposed map for any new content, which we add in the future.
CentOS-devel mailing list CentOS-devel@centos.org https://lists.centos.org/mailman/listinfo/centos-devel
On 06/09/2023 17:04, Aleksandra Fedorova wrote:
On 9/6/23 16:48, Fabian Arrotin wrote:
On 06/09/2023 15:47, Aleksandra Fedorova wrote:
Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://hackmd.io/@bookwar/centos-docs-layout
The link has more details but in short we need three categories of content:
* User Documentation: everything about installing and administering the CentOS system. Large guides go here, as well as small Knowledge Base articles.
* Project Documentation: All about processes and policies of the CentOS Project.
* SIGs documentation: Documentation subtrees maintained by each Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide (https://sigs.centos.org/guide/) belongs to the "Project Documentation" section in this hierarchy.
These ones (SIGs docs) already exist and are all rendered via mkdocs (from various git repositories) and so already under https://sigs.centos.org so no need to change the existing (and working) workflow :-)
Yes, I forgot to say it explicitly:
I do not propose to put all docs into one repository. Or even to use the same tooling. Existing guides should stay where the are.
The idea is that we should have a defined hierarchy and a path how to get to the SIG Guide from the top page on docs.centos.org. And it is perfectly fine if following that path you use an external link and land on a different site built by a different tool.
So the *link* to the SIG Guide will be in the Project Documentation section on doc.centos.org.
Same for other parts of the documentation:
Ah ! makes sense .. and yes, huge +1 to have finally docs.centos.org the main entry point even if itself would either host docs or have pointers to other docs :-)
Thanks so much for your work on this and the further clarification! I really like the layout and the acknowledgement that things that are currently working where they are do not need to be changed:)
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 Wed, Sep 6, 2023 at 10:28 AM Fabian Arrotin arrfab@centos.org wrote:
On 06/09/2023 17:04, Aleksandra Fedorova wrote:
On 9/6/23 16:48, Fabian Arrotin wrote:
On 06/09/2023 15:47, Aleksandra Fedorova wrote:
Hi, folks,
I was playing with the ways to organize the CentOS Documentation site and came up with the following proposal:
https://hackmd.io/@bookwar/centos-docs-layout
The link has more details but in short we need three categories of content:
- User Documentation: everything about installing and administering
the CentOS system. Large guides go here, as well as small Knowledge Base articles.
- Project Documentation: All about processes and policies of the
CentOS Project.
- SIGs documentation: Documentation subtrees maintained by each
Special Interest group on their own.
Note that by SIG docs here I mean documentation written and owned by individual special interest groups. The current SIG Guide (https://sigs.centos.org/guide/) belongs to the "Project Documentation" section in this hierarchy.
These ones (SIGs docs) already exist and are all rendered via mkdocs (from various git repositories) and so already under https://sigs.centos.org so no need to change the existing (and working) workflow :-)
Yes, I forgot to say it explicitly:
I do not propose to put all docs into one repository. Or even to use the same tooling. Existing guides should stay where the are.
The idea is that we should have a defined hierarchy and a path how to get to the SIG Guide from the top page on docs.centos.org. And it is perfectly fine if following that path you use an external link and land on a different site built by a different tool.
So the *link* to the SIG Guide will be in the Project Documentation section on doc.centos.org.
Same for other parts of the documentation:
Ah ! makes sense .. and yes, huge +1 to have finally docs.centos.org the main entry point even if itself would either host docs or have pointers to other docs :-)
-- Fabian Arrotin The CentOS Project | https://www.centos.org gpg key: 17F3B7A1 | @arrfab[@fosstodon.org]
CentOS-devel mailing list CentOS-devel@centos.org https://lists.centos.org/mailman/listinfo/centos-devel
-
Aleksandra Fedorova -
Amy Marrich -
Fabian Arrotin -
Patrick Riehecky