Bazel 문서 스타일 가이드

Nightly · 9.1 · 9.0 · 8.7 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Bazel 문서에 기여해 주셔서 감사합니다. 이 문서는 시작하는 데 도움이 되는 간단한 문서 스타일 가이드입니다. 이 가이드에서 답변하지 않는 스타일 관련 질문은 Google 개발자 문서 스타일 가이드를 따르세요.

원칙 정의

Bazel 문서는 다음 원칙을 준수해야 합니다.

  • 간결함. 가능한 한 적은 단어를 사용합니다.
  • 명확함. 쉬운 언어를 사용합니다. 5학년 읽기 수준에 맞게 전문 용어를 사용하지 않고 작성합니다.
  • 일관성. 문서 전체에서 반복되는 개념에 동일한 단어나 구문을 사용합니다.
  • 정확함. 시간 기반 정보와 미래에 대한 약속을 피하여 콘텐츠가 최대한 오랫동안 정확하게 유지되도록 작성합니다.

쓰기

이 섹션에는 기본적인 작성 도움말이 포함되어 있습니다.

제목

  • 페이지 수준 제목은 H2부터 시작합니다. (H1 제목은 페이지 제목으로 사용됩니다.)

  • 헤더를 적절히 짧게 만듭니다. 이렇게 하면 줄바꿈 없이 목차에 맞게 표시됩니다.

    • 예: 권한
    • 아니요: 권한에 관한 간단한 참고사항

  • 제목에는 문장 첫 글자를 대문자로 표기하는 규칙을 사용합니다.

    • 예: 작업공간 설정
    • 아니요: 작업공간 설정

  • 제목을 작업 기반 또는 실행 가능한 제목으로 만듭니다. 제목이 개념적인 경우 이해를 기반으로 할 수 있지만 사용자가 수행하는 작업을 작성합니다.

    • 예: 그래프 순서 유지
    • 아니요: 그래프 순서 유지

이름

  • Bazel 및 Starlark와 같은 고유명사는 대문자로 표기합니다.

    • 예: 빌드가 끝나면 Bazel이 요청된 대상을 출력합니다.
    • 아니요: 빌드가 끝나면 bazel이 요청된 대상을 출력합니다.

  • 일관성을 유지해야 합니다. 기존 개념에 새로운 이름을 도입하지 마세요. 해당하는 경우 용어집에 정의된 용어를 사용합니다.

    • 예를 들어 터미널에서 명령어 실행에 관해 작성하는 경우 페이지에서 터미널과 명령줄을 모두 사용하지 마세요.

페이지 범위

  • 각 페이지에는 하나의 목적이 있어야 하며, 이 목적은 시작 부분에 정의되어야 합니다. 이렇게 하면 독자가 필요한 내용을 더 빠르게 찾을 수 있습니다.

    • 예: 이 페이지에서는 Windows에 Bazel을 설치하는 방법을 설명합니다.
    • 아니요: (소개 문장이 없음)

  • 페이지 끝에 독자가 다음에 해야 할 일을 알려줍니다. 명확한 작업이 없는 페이지의 경우 유사한 개념, 예시 또는 기타 탐색 방법으로 연결되는 링크를 포함할 수 있습니다.

제목

Bazel 문서에서 잠재고객은 주로 사용자, 즉 Bazel을 사용하여 소프트웨어를 빌드하는 사람들이어야 합니다.

  • 독자를 '사용자'라고 지칭합니다. (어떤 이유로든 '사용자'를 사용할 수 없는 경우 '그들'과 같은 성 중립적인 언어를 사용합니다.)

    • 예: Bazel을 사용하여 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
    • 가능: 사용자가 Bazel로 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
    • 아니요: 사용자가 Bazel로 Java 코드를 빌드하려면 JDK를 설치해야 합니다.

  • 잠재고객이 일반적인 Bazel 사용자가 아닌 경우 페이지 또는 섹션의 시작 부분에 잠재고객을 정의합니다. 기타 잠재고객에는 유지관리자, 기여자, 이전자 또는 기타 역할이 포함될 수 있습니다.

  • 'Google'은 사용하지 마세요. 사용자 문서에는 작성자가 없습니다. 가능한 작업을 사용자에게 알려주기만 하면 됩니다.

    • 예: Bazel이 발전함에 따라 호환성을 유지하려면 코드베이스를 업데이트해야 합니다.
    • 아니요: Bazel이 발전하고 있으며 Google은 Bazel 사용자에게 비호환되고 일부 변경이 필요한 Bazel을 변경할 예정입니다.

Temporal

가능한 경우 특정 날짜 (2022년 2분기)를 참조하거나 '지금', '현재' 또는 '곧'이라고 말하는 등 시간상으로 방향을 지정하는 용어는 피하세요. 이러한 용어는 빠르게 오래되고 미래 예측인 경우 부정확할 수 있습니다. 대신 'Bazel X.x 이상에서 <기능> 또는 GitHub 문제 링크를 지원합니다'와 같이 버전 수준을 지정합니다.

  • 예: Bazel 0.10.0 이상에서 원격 캐싱을 지원합니다.
  • 아니요: Bazel은 곧 원격 캐싱을 지원할 예정이며, 2017년 10월에 지원할 가능성이 높습니다.

긴장감 있는 음악

  • 현재 시제를 사용합니다. 명확성을 위해 꼭 필요한 경우가 아니라면 과거 또는 미래 시제는 피하세요.

    • 예: Bazel은 이 규칙을 준수하지 않는 종속 항목을 발견하면 오류를 발생시킵니다.
    • 아니요: Bazel이 이 규칙을 준수하지 않는 종속 항목을 발견하면 Bazel이 오류를 발생시킵니다.

  • 가능한 경우 수동태 (주어가 객체에 작용하는 경우)가 아닌 능동태 (객체가 주어에 의해 작용되는 경우)를 사용합니다. 일반적으로 능동태는 누가 책임을 지는지 보여주므로 문장을 더 명확하게 만듭니다. 능동태를 사용하면 명확성이 떨어지는 경우 수동태를 사용합니다.

    • 예: Bazel은 X를 시작하고 출력을 사용하여 Y를 빌드합니다.
    • 아니요: X는 Bazel에 의해 시작된 후 출력을 사용하여 Y가 빌드됩니다.

어조

비즈니스 친화적인 어조로 작성합니다.

  • 구어체는 피하세요. 영어에만 해당하는 구문은 번역하기가 더 어렵습니다.

    • 예: 좋은 규칙 집합
    • 아니요: 좋은 규칙 집합이란 무엇인가요?

  • 지나치게 격식을 차린 표현은 피하세요. 기술에 관심이 있지만 세부정보는 모르는 사람에게 개념을 설명하는 것처럼 작성합니다.

형식 지정

파일 형식

가독성을 위해 80자에서 줄바꿈합니다. 긴 링크 또는 코드 스니펫은 더 길 수 있지만 새 줄에서 시작해야 합니다. 예를 들면 다음과 같습니다.

  • '여기' 또는 '아래' 대신 설명이 포함된 링크 텍스트를 사용합니다. 이렇게 하면 문서를 더 쉽게 스캔할 수 있고 화면 읽기 프로그램에 더 적합합니다.

    • 예: 자세한 내용은 [Bazel 설치]를 참고하세요.
    • 아니요: 자세한 내용은 [여기]를 참고하세요.

  • 가능한 경우 링크로 문장을 끝냅니다.

    • 예: 자세한 내용은 [링크]를 참고하세요.
    • 아니요: 자세한 내용은 [링크] 를 참고하세요.

목록

  • 순서가 지정된 목록을 사용하여 단계별로 작업을 완료하는 방법을 설명합니다.
  • 순서가 지정되지 않은 목록을 사용하여 작업 기반이 아닌 항목을 나열합니다. (알파벳순, 중요도 등과 같은 순서가 있어야 합니다.)
  • 병렬 구조로 작성합니다. 예를 들면 다음과 같습니다.
    1. 모든 목록 항목을 문장으로 만듭니다.
    2. 동일한 시제의 동사로 시작합니다.
    3. 따라야 할 단계가 있는 경우 순서가 지정된 목록을 사용합니다.

자리표시자

  • 사용자가 변경해야 하는 변수를 나타내려면 꺾쇠괄호를 사용합니다. 마크다운에서 백슬래시로 꺾쇠괄호를 이스케이프 처리합니다(\<example\>).

    • 예: bazel help <command>: 도움말 및 옵션을 출력합니다. <command>
    • 아니요: bazel help command: 도움말 및 'command'의 옵션을 출력합니다.

  • 특히 복잡한 코드 샘플의 경우 컨텍스트에 적합한 자리표시자를 사용합니다.

목차

사이트에서 지원하는 자동 생성된 목차를 사용합니다. 수동 목차를 추가하지 마세요.

코드

코드 샘플은 개발자에게 유용한 도구입니다. 이미 작성 방법을 알고 계시겠지만 몇 가지 도움말을 소개합니다.

작은 코드 스니펫을 참조하는 경우 문장에 삽입할 수 있습니다. 독자가 명령어를 복사하는 등 코드를 사용하도록 하려면 코드 블록을 사용합니다.

코드 블록

  • 간략하게 만듭니다. 코드 샘플에서 중복되거나 불필요한 텍스트를 모두 삭제합니다.
  • 마크다운에서 샘플의 언어를 추가하여 코드 블록의 유형을 지정합니다.
```shell
...
  • 명령어와 출력을 서로 다른 코드 블록으로 구분합니다.

인라인 코드 형식

  • 파일 이름, 디렉터리, 경로, 작은 코드 조각에는 코드 스타일을 사용합니다.
  • _기울임꼴_, "따옴표" 또는 **굵게** 대신 인라인 코드 스타일을 사용합니다.
    • 예: bazel help <command>: 도움말 및 옵션을 출력합니다. <command>
    • 아니요: bazel help command: 도움말 및 'command'의 옵션을 출력합니다.