콘텐츠로 이동

Rocky Linux 문서 스타일 가이드

Rocky Linux는 기여자들과 함께 급속도로 성장하고 있는 엔터프라이즈 리눅스로, 문서화 역시 여러분과 같은 기여자들 덕분에 급증하고 있습니다. 여러분의 콘텐츠는 어떤 형식으로든 환영합니다. RL 문서 편집자들은 여러분과 협력하여 표준에 따라 포맷을 조정해주거나 도와드릴 것입니다.

소개

개요

새로운 기여는 Rocky Linux 사용에 관한 정보를 웹 상에서 완벽한 공간으로 발전시키는 데 환영합니다. 여러분은 자신이 이해하기 쉬운 형식으로 문서를 작성할 수 있으며, 문서 팀은 여러분과 협력하여 Rocky 가족의 일부로 보이고 느껴지도록 포맷을 수정하거나 도와줄 것입니다.

이 가이드는 Rocky Linux 문서 전반에 걸쳐 가독성을 향상시키고, 특별한 경우를 강조하며, 번역 작업을 원활하게 하는 영어 스타일 표준을 설명합니다. 이 가이드에서 다루지 않은 스타일 문제에 대해서는 다음 사항을 참고하십시오:

기여하기

기여에 대해 더 자세히 알아보려면 다음과 같은 가이드를 참고하십시오:

스타일 가이드라인

RL 문서는 액세스 가능성을 향상시키고 지속적인 번역 작업을 돕기 위해 명확하고 일관된 언어를 사용하도록 노력합니다.

문법과 문장 부호

시카고 매뉴얼 오브 스타일에서 기술 문서 작성의 특징은 다음과 같습니다:

  • ‘옥스퍼드 스타일’이 아닌 ‘시카고 스타일’을 따라 이중 인용 부호(“”)를 사용합니다.
  • 마침표와 쉼표는 "like this".가 아니라 "like this," 처럼 따옴표 안에 들어갑니다.
  • 전각 대시 {shift}+{option}+{-}는 이와 같이 앞뒤에 공백이 없으며 괄호로 묶인 문장에 선호됩니다.
  • "완두콩, 겨자, and 당근"의 세 가지 항목 목록에서 "and" 앞에 시리얼 쉼표를 사용합니다.
  • 제목은 일반적으로 헤드라인 스타일 대문자화를 사용합니다: 첫 번째와 마지막 단어, 그리고 모든 명사, 대명사, 동사, 부사를 대문자화합니다. 문서에서 빈번한 약어를 참조하는 경우 문장 스타일 대문자화로 더 나은 결과가 나오면 문서 전체적으로 일관성 있게 작성하면 됩니다.
  • 제목은 약어로 끝나지 않는 한 문장 스타일의 대문자를 사용하더라도 끝에 마침표나 세미콜론이 필요하지 않습니다.

목소리와 톤

  • 일반 언어 사용. 이것은 대화가 적은 스타일로 설명할 수 있습니다. 대부분의 문서는 이 기준에 따릅니다.
    • 은유와 관용구를 피하십시오.
    • 가능한 한 적은 단어로 의미하는 바를 말하십시오.
    • 불필요하게 기술적인 용어를 식별하고 피합니다. 대상 독자들은 해당 주제에 어느 정도 익숙하지만 전문가는 아닐 수 있기 때문에 고려해야 합니다.
    • 일반적으로 평범한 언어에 예외가 있습니다:
      • 초보자나 비전문가 대상 문서나 블로그 포스트와 같은 콘텐츠의 경우 보다 대화식 스타일이 적합합니다.
      • 고급 사용자나 API(Application Programming Interface) 문서를 대상으로 한 문서의 경우 보다 공식적이거나 간결한 어조가 적합합니다.
  • 포괄적인 언어 사용.
    • 언어 사용은 시간이 지남에 따라 진화합니다. 특정 단어는 부정적인 의미를 가지고 있으므로 문서를 새로운 단어를 사용하도록 다시 작성해야 합니다.
      • Master/slave는 primary/secondary 또는 합의된 조직 표준에 따라 결정됩니다.
      • Blacklist/whitelist은 blocklist/allowlist 또는 합의된 조직 표준에 따라 결정됩니다.
      • 기타 관련 예시들을 고려하여 문서를 작성할 수 있습니다.
    • unknown 또는 non-binary 성별을 언급할 때 “they”를 단수 대명사로 사용하는 것이 허용됩니다.
    • 자신의 능력에 대해 말할 때 한계가 아닌 능력으로서의 답변을 제시합니다. 예를 들어, Rocky Linux에서 Steam을 실행하는 문서가 있는지 궁금하다면, 그것은 단순히 “아니오”가 아닌 “너가 우리 트리에 추가할 수 있는 좋은 곳이야!”와 같이 대답합니다.
  • 약어를 사용하지 않습니다. 이것은 번역 작업을 돕습니다. 다만 블로그 포스트나 커뮤니티의 새 멤버를 위한 환영 지침과 같이 대화식 스타일로 작성하는 경우는 예외입니다.

Formatting - 서식

날짜

가능한 경우 날짜 형식으로 {day} {Month} {year}을 사용합니다. 그러나 명확성이나 외관 문제를 해결하기 위해 {Month} {day}, {year}도 허용됩니다. 어떤 방법을 선택하더라도 혼동을 피하기 위해 숫자의 나열 대신 월 이름을 글로 쓰세요. 예를 들어: 2023년 1월 24일, 그러나 1월 24일 2023년도도 허용 가능합니다 — 1/24/2023 또는 24/01/2023보다는 양쪽이 더 우선합니다.

단일 단계 절차

한 단계로 구성된 절차는 숫자 대신 불릿을 사용합니다. 예를 들어:

  • 이 아이디어를 구현하고 넘어갑니다.

그래픽 인터페이스 언어

  • UI에 대한 텍스트 지침: 사용자 인터페이스에 입력해야 하는 명령을 설명할 때 "put"이나 "type" 대신에 "enter"라는 단어를 사용합니다. 명령을 코드블록으로 작성하세요(즉, 역따옴표로 감싸세요).

예제 Markdown 텍스트 **포맷** 메뉴에서 **줄 간격**을 클릭합니다.

  • UI 요소 이름: 버튼, 메뉴 항목, 대화 상자 이름 등 UI 요소의 이름은 강조하여 작성하세요. 단어가 클릭 가능하지 않더라도 강조하세요.

예제 Markdown 텍스트 **커밋 메시지** 상자에 update_thisdoc를 입력합니다.

구조

가이드의 시작 콘텐츠 또는 책의 페이지/장의 시작 콘텐츠

  • 요약. 이 페이지에서 기대되는 내용에 대한 간단한 설명
  • 목표. 이 페이지가 독자에게 전달할 내용을 나열한 목록
  • 필요하거나 학습된 기술
  • 난이도 수준. 쉬운 경우 1, 중간 수준인 경우 2 등으로 표시합니다.
  • 소요 시간. 문서의 단어 수를 1분에 75단어로 나누어 이 숫자를 계산합니다.

Admonition(경고)

Markdown 내에서 경고는 정보를 강조하기 위해 상자에 정보를 담는 방법입니다. 문서에 필수적인 요소는 아니지만 유용한 도구입니다. Rocky 서식 문서에서 주의에 대해 더 알아보세요.

접근성

다음 표준은 스크린 리더 등 접근 보조 기기를 사용하는 사람들의 접근성을 향상시킵니다.

이미지

  • 다이어그램, 이미지 또는 아이콘과 같은 비텍스트 항목에는 alt 텍스트 또는 캡션을 제공합니다.
  • 가능하면 텍스트 스크린샷을 사용하지 마세요.
  • alt 텍스트를 의미 있게 작성합니다. 예를 들어, 액션 아이콘의 경우 모습을 설명하는 대신 기능에 대한 설명을 입력합니다.

링크

  • 링크를 설명적으로 작성하여 텍스트 자체 또는 문맥에서 링크가 어디로 이동할지 명확하게 합니다. "여기를 클릭하세요."와 같은 이름을 가진 하이퍼링크를 피합니다.
  • 모든 링크가 설명한 대로 작동하는지 확인합니다.

테이블

  • 왼쪽에서 오른쪽으로, 위에서 아래로 논리적 순서로 테이블을 만듭니다.
  • 표의 상단이나 왼쪽에 빈 셀을 두지 마십시오.
  • 여러 열에 걸쳐 있는 병합된 셀을 피하십시오.

색상

  • Markdown의 일부 요소는 시각적 이해를 돕기 위해 지정된 색상이 있습니다. 일반적으로 이러한 요소는 이름이 지정되어 있습니다. 예를 들어, "위험" 주의는 빨간색 박스로 표시되지만 "위험" 설명이 포함되어 있습니다. 그러나 사용자 정의 주의를 작성할 때는 색상만으로 명령이나 경고 수준을 전달하지 않도록 주의해야 합니다.
  • 위 또는 아래, 색상, 크기, 페이지의 시각적 위치 등도 포함해야 합니다. 텍스트 설명으로만 전달할 수 있는 방향입니다.
  • 그래픽 요소를 작성할 때 전경과 배경 색상 사이에 충분한 대비가 있는지 스크린 리더가 해석하기 쉽도록 확인합니다.

제목

  • 모든 수준의 제목을 건너뛰지 않고 모든 제목 수준을 사용합니다.
  • 가독성을 높이기 위해 모든 자료를 제목 아래에 중첩합니다.
  • Markdown에서는 하나의 제목 1 레벨만 사용할 수 있다는 점을 기억하세요.

요약

이 문서는 스타일 가이드라인, 문서 구조 및 통합하는 방법을 포함한 Google의 기여 표준을 설명합니다. 텍스트에 대한 포용성 및 접근성. 이것이 우리가 추구하는 표준입니다. 가능한 한 문서를 작성하고 수정할 때 이러한 표준을 염두에 두십시오.

그러나 이러한 경고를 놓치지 말고 이러한 표준을 장애물이 아닌 도구로 취급해야 합니다. 포용성과 접근성의 정신으로 인해 여러분의 기여가 원활하게 Rocky 패밀리 트리로 포함되도록 하고 싶습니다. 우리는 친근하고 도움이 되는 문서 작가와 스타일리스트의 팀이며, 여러분의 문서가 최종적인 형태로 이끌리도록 도와드릴 것입니다.

준비되셨나요? 시작해봅시다!

Author: Ezequiel Bruni, Krista Burdine

Contributors: Steven Spencer