/documentation

Official Rocky Linux documentation repository.

Contribution Guide

All Contributors

Introduction

With Rocky Linux emerging as a major RHEL-compatible distribution, this is an exciting time in the open source community. Rocky Linux’s mission is to provide companies and individuals with a stable foundation of open source software for their enterprise and HPC needs. We are here to support that mission with excellent documentation.

To us, excellent documentation hits these marks:

  • Educate users how to admin this distribution and its associated programs.
  • Support users of all skill levels with manuals and troubleshooting guides to make the most of this distribution.
  • Apply a consistent standard across all related documents, for ease of reading and translation.
  • Keep documentation up to date (and error free) with current versions.
  • Allow users to contribute Guides, Docs, Gemstones (scripts and favorite code snippets) and more, to enhance Rocky Linux for fellow users.

We welcome anyone who wants to be part of this mission. No specific degree, years of experience, or company affiliation required. Be bold! We promise, you won’t break anything even if you fumble your first attempt.

Technical requirements

Our standards for Rocky documentation.

Style Guide

The RL Style Guide outlines standards for the wording within your document.

GitHub

Rocky Linux uses GitHub to manage its code and files, including documentation files. Login to GitHub and follow the official Rocky Linux documentation repository.

Markdown

Documentation is welcome in whatever format you are used to creating. It does not need to be perfect, just submit what you have and the team will give you feedback to help get it in line with our voice and tone.

That said, RL Documentation uses Markdown as the standard. It is easy to learn and use. Run a text converter on your content or start from scratch with this basic writing and formatting guide by GitHub.

As you become a regular contributor, you’ll need to create a local repository. See our [guide](link to the first time contributor guide, once published) for how to install a Markdown editor and create a local repository on your home computer.

Contribution Process

The actual process of reporting an issue, revising, or creating a doc. Please see special notes afterward about translations, links, and meta content.

Report an issue

Maybe you’ve found a broken link or incorrect information while exploring the Rocky docs. This is called an issue, and we want to know about it. You can mention it on the Mattermost Documentation channel, or visit GitHub and make a proper issue report. GitHub has a handy guide for how to create an issue.

Submit an update

Add a missing word, correct an error, clarify a confusing bit of text. You won’t break anything because someone will review your contribution before it goes live. Here is the basic process.

  1. Start on the page you want to update on https://docs.rockylinux.org/.

    Click the “Edit” pencil in the upper right corner of the document. You will be taken to the original document stored on GitHub.

    The first time you contribute to the RL repository, you will be prompted with a green button to “Fork this repository and propose changes.” This creates a duplicate copy of the RL repository where you make your suggested edits. Click the green button and continue.

  2. Make your changes

    Follow the existing Markdown formatting. Make the necessary change.

  3. Propose changes

    At the bottom of the page, write a brief description in the title of the block entitled Propose changes.

    Then click Propose changes, which will Commit your changes to a completed document within your forked repository.

  4. Review changes

    Now you can look at what you’ve done, line by line. If you missed anything, back up to the previous page and correct it again (you’ll have to start over), then click Propose Changes again.

    Once the doc is the way you want it, click the green button that says Create Pull Request. This provides one more chance to double check your changes and confirm the doc is ready.

  5. Create Pull Request

    So far you have been working in your own repository. Next you submit it to the documentation team to merge your version into the main version of the document.

    Click the green button that says Create Pull Request, which sends it to the RL documentation team for review.

  6. Wait

    Once the RL team reviews your request, they will respond in one of three ways.

    • Accept and merge your PR
    • Comment with feedback and ask for changes
    • Deny your PR with explanation

    If you have to make changes, you will suddenly understand why you need a local repository. The team can talk you through what to do next. In good news, it’s still fixable.

Need more in-depth explanation? Here are the same directions with more words and illustrations.

Success? Welcome to the team, you are officially a Rocky Linux documentation contributor. Your profile will be added to the contributor list at the bottom of this document shortly.

Become a frequent contributor

For more than a word or two of occasional edits, we recommend that you [setup a local repository](add link to how to create a new document, once published) on your own machine. From there, you can revise documentation from your clone of the RL repository, Commit it to your online GitHub repository, and then create Pull Requests to merge with the main repository.

Advanced users may wish to create a complete documentation server on your local Linux workstation or VM. We have guides to set that up with Docker or LXD. We also have a fast documentation system with special caveats if you are using Python on the same server.

Submit a new document

Rocky Linux documentation includes guides, books, labs, and gemstones. Your original contributions are welcome in any of these categories.

Meta

Please include the following meta information at the top of all new documentation:


title: Document title

author: the author of the source (English) version of the document.

contributors: a comma separated list of contributors to the source document.

tested with: a comma separated list of versions example: 8.6, 9.0

tags:

  • displayable tags

  • these are also searchable

  • they are two space indented and start with a "-" as shown here

  • generally, they should be one word


Formatting

To add more advanced elements to your Markdown-formatted document beyond text, visit the formatting guide. This covers Admonitions, Tables, Quotes, and more.

Contribute

The process for [submitting original content](link to first time contributors guide, once published) is similar to updating an existing document from your local repository. Create a new document within your Markdown editor, Commit it to your GitHub repository, then submit a Pull Request to merge into the main branch of the repository. The documentation leads will decide where the new document will live.

Special Notes

Links

Links can be internal (other docs within our domain), external (publicly hosted URLs), or lab-based (used as examples within your document).

The format for all links within the documentation is square brackets around the descriptive name or label:

[our site] followed by your link in parenthesis: (https://example.com)

To help lab-based URLs pass our automatic URL checker, we have created a list of excluded names you may use. You may request that a new exclusion be added. An editor may adjust your lab-based URL, or add an exclusion if they think it is warranted.

  • example.com
  • site.com
  • site1.com
  • site2.com
  • apache-server
  • nginx-server
  • your-server-ip
  • your-server-hostname
  • localhost

Translation

CrowdIn

We are adding to these docs in new languages at the speed of getting translators on board. Seeking contributors for this area especially. We use CrowdIn for updates.

Translation and Meta content

Translators, if you find a word in the source document that does not translate well into your language, or an error that prevents a perfect translation, please fix that in the source document and make a Pull Request. In that case, please add yourself as a contributor in the meta content of that document.

However, unless you modify the source document, please do not modify the meta content.

The place where we do want to acknowledge you is in the all-contributors section--at the bottom of this page. This is a list of everyone who has been part of this documentation project, whether creating content, spotting and fixing errors, or translating. Translators, you may add yourself (or request to be added) here. We appreciate your contribution!

Communication channel

For reporting issues, asking questions, getting support, and getting to know the documentarians.

For general questions about installing and using the distro, visit our community forums. For questions about the behind-the-scenes stuff like documentation, we have other channels.

Mattermost

To ask real-time questions, create a profile on the Mattermost server, then navigate to the Rocky Linux General or Documentation channel--or whichever channel seems appropriate to your question. You should get a response within hours if not right away.

Welcome aboard! Meet the rest of our awesome contributors below: (emoji key):

wale soyinka
wale soyinka

📆 🚧 🖋
sspencerwire
sspencerwire

📆 🚧 🖋
Ezequiel Bruni
Ezequiel Bruni

🚧 🖋
ambaradan
ambaradan

🌍
Antoine Le Morvan
Antoine Le Morvan

🖋 🌍
tianci li
tianci li

🖋 🌍
student
student

🖋
NezSez
NezSez

🖋 🤔
justasojourner
justasojourner

🖋 🤔
Neil Hanlon
Neil Hanlon

🖋 🚧 🤔
Peter Ajamian
Peter Ajamian

🖋
Flávio Siqueira Prado
Flávio Siqueira Prado

🌍
Norio4
Norio4

🌍
Sébastien Pascal-Poher
Sébastien Pascal-Poher

🌍
Lucas Trecanao
Lucas Trecanao

🌍
calderds
calderds

🖋 👀
execion
execion

🌍
lillolollo
lillolollo

🖋
Ahmed alBattashi
Ahmed alBattashi

🖋
StackKorora
StackKorora

🖋
3xtant
3xtant

🖋
almrv
almrv

🌍
Hayden
Hayden

🖋
Louis Abel
Louis Abel

🖋
Ron
Ron

🖋
Amin Vakil
Amin Vakil

🖋
K.Prasad
K.Prasad

🖋
IncorrigiblyBelligerent
IncorrigiblyBelligerent

🖋
Jairo Nonato Júnior
Jairo Nonato Júnior

🖋
Saif Eddine Halila
Saif Eddine Halila

🖋
DrCool2
DrCool2

🖋
codedude
codedude

🖋
Graham
Graham

🖋
Aditya Putta
Aditya Putta

🖋
yangxuan74
yangxuan74

🖋
Morgan Read
Morgan Read

🖋
9p4
9p4

🖋
Alex Zimmerman
Alex Zimmerman

🖋
Andrew Faulkner
Andrew Faulkner

🖋
Todd Levi
Todd Levi

🖋
tahder
tahder

🖋
Takahiro Yoshihara
Takahiro Yoshihara

🖋
Gerard Arthus
Gerard Arthus

🖋
HadManySons
HadManySons

🖋
Brandon Mayfield
Brandon Mayfield

🖋
Anthony Staunton
Anthony Staunton

🖋
whg517
whg517

🖋
MrSkribb
MrSkribb

🖋
jules
jules

🖋
Brendan Fattig
Brendan Fattig

🖋
bittin
bittin

🖋
ichibariki
ichibariki

🖋
Bernat Puigdomenech Pascual
Bernat Puigdomenech Pascual

🖋
Dennis Körner
Dennis Körner

🖋
Pedro Bezunartea López
Pedro Bezunartea López

🌍
Daniel Pogac
Daniel Pogac

🖋
oats
oats

🖋
Alex Harden
Alex Harden

🖋
Jordan Pisaniello
Jordan Pisaniello

🖋
Richard Hennig
Richard Hennig

🖋
caffenix
caffenix

🖋
Lento Manickathan
Lento Manickathan

🖋
Alan Sill
Alan Sill

🖋
Ikko Ashimine
Ikko Ashimine

🖋
William Perron
William Perron

🖋
Roman Gherta
Roman Gherta

🖋
Yiğit can BAŞALMA
Yiğit can BAŞALMA

🖋
markooff
markooff

🖋 🌍
Deng Wenbin
Deng Wenbin

🌍
alikates
alikates

🖋
hopnux
hopnux

🌍
Pedro Garcia Rodriguez
Pedro Garcia Rodriguez

🌍
Lau
Lau

🖋
Serge Croisé
Serge Croisé

🖋
bamtests
bamtests

🖋
jahway603
jahway603

🖋
Nejc Bertoncelj
Nejc Bertoncelj

🖋
Dan Baker
Dan Baker

🖋
Laura Hild
Laura Hild

🖋
Grammaresque
Grammaresque

🖋
Brent Dacus
Brent Dacus

🖋
Rawk Akani
Rawk Akani

🖋

This project follows the all-contributors specification. Contributions of any kind welcome!