Web+Docs Hackfest FOSDEM 2024

• bookwar's proposed docs layout:

  • https://hackmd.io/@bookwar/centos-docs-layout

• upstream rhel docs are special

• everything else md+mkdocs

• have "quick docs" but do it as a doc in mkdocs

• user docs: rhel, quickdocs

• project docs: contributors, policy, governance

• git layout: one repo per document

• all on gitlab, move contributors guide

  • centos-docs - landing
  • quick-docs repo
  • project-docs repo (including Contributor guide and policies and governance)

• docs.centos.org periodically runs ansible role and updates the site if the sources changed

• do the docs.std.centos.org and switch to it

• add CI for Merge Requests - the preview of the site generated on MR

• license: use whatever fedora uses (cc-by-sa 4.0)

• fabian to push ci/cd to render previews

• lots of conversation about i18n/l10n

  • concerns about quality control and workload
  • adding translation is not a good entry point contribution. To add language create a SIG and prove that you are capable and trustworthy, same way as a with code contribution

• Centos-events repo for data about of former events

• fabian to do ansible role for front docs.c.o like sigs.c.o

Draft Outreachy project description

The CentOS project has documentation work that can be roughly grouped into two categories: upstreamed RHEL docs and community docs. There is a buffet of tasks, many of them independant of each other, and we do not expect that an intern will be able to do everything.

Upstreamed RHEL docs: We are able to adapt and publish the CC-licensed documentation from Red Hat Enterprise Linux. The RHEL docs team has already set up the infrastructure to do this. However, there remains a lot of work to be done in using asciidoc conditionals to adapt the content. A general understanding of Linux systems will be helpful, but you do not need to be an expert. Prior experience with asciidoc will give you a head start, but it's easy to learn regardless. We would also like you to document as you go, so future contributors will have an easier time with this ongoing work.

Additionally on the RHEL docs, there is some work that can be done around deployment. The tooling is largely already built, but there remains some work to integrate and deploy. This may involve Python, Ruby, and containerization technologies like Podman. This work is entirely optional. You do not need to know these technologies to apply. This is just an extra learning opportunity.

Community docs: We also have docs specific to CentOS that we cannot get from RHEL. These include our Contributors Guide and the various guides from our Special Interest Groups (SIGs). We are moving toward markdown published with mkdocs for these guides. There are a number of tasks that can be done here. One task is to work on deploying mkdocs for community docs, which may involve Python and Podman. It is already deployed for the SIG docs, so we don't expect roadbumps with the tools.

The Contributors Guide is currently written in asciidoc, so it would need to be converted to markdown for the new system. Automated tooling can probably handle most of this. The Contributors Guide is also incomplete, and in places out of date. We need somebody to carefully review it, talk to subject matter experts, and help develop new content. A general understanding of Linux and open source will help, but you do not need expertise in contributing to CentOS. Technical writing is largely about coordinating information from people who are experts in the area.

There are also a number of howtos and tutorials on our wiki archive. We had to archive our wiki last year due to unmaintained tools, but we weren't able to migrate all the content to a new home in time. You could look thru the content on the wiki archive to find which content is still useful, then adapt that content to the new community docs system. Again, you do not need to be an expert on how useful the content is or what it may be missing. You will work with experts to determine this.

Finally, there is design work that could be done and implemented on both documentation systems. This is entirely optional. We can deploy with very minimal branding. Neither of your mentors is experienced with graphic design. However, if this is an area you're interested in, we can connect you to the CentOS Artwork SIG and the Fedora Design Team.