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