Bazel 문서 스타일 가이드

문제 신고 소스 보기

Bazel의 문서에 참여해 주셔서 감사합니다. 시작하는 데 도움이 되는 빠른 문서 스타일 가이드 역할을 합니다. 이 가이드에 답변되지 않은 스타일 질문은 Google 개발자 문서 스타일 가이드를 따르세요.

원칙 정의

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

  • 간결함. 가능한 한 적은 단어를 사용합니다.
  • 삭제 평이한 언어를 사용하세요. 전문 분야 없이 5학년 읽기 수준에 맞춰 작성하세요.
  • 일관성. 문서 전체에서 동일한 개념이나 개념을 반복해서 사용합니다.
  • 정답입니다. 시간 기반의 정보와 미래에 대한 약속을 피함으로써 콘텐츠가 최대한 오랫동안 유지되는 방식으로 작성합니다.

쓰기

이 섹션에서는 기본적인 작성 팁을 다룹니다.

제목

  • 페이지 수준 제목은 H2에서 시작합니다. (H1 제목은 페이지 제목으로 사용됩니다.)
  • 헤더는 최대한 짧아야 합니다. 이렇게 하면 래핑 없이 TOC에 맞습니다.

    • : 권한
    • 아니요: 권한에 대한 간단한 참고사항
  • 제목에 문장 첫 글자 대문자 사용

    • : 작업공간을 설정합니다.
    • 아니요: 작업공간을 설정합니다.
  • 제목을 작업 기반 또는 실행 가능하게 만드세요. 제목이 개념인 경우 이해를 기반으로 할 수 있지만 사용자가 하는 작업에 작성합니다.

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

이름

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

    • : 빌드가 끝나면 Bazel이 요청된 대상을 출력합니다.
    • 아니요: 빌드가 끝나면 bazel에서 요청된 타겟을 출력합니다.
  • 일관성을 유지하세요. 기존 개념에 새 이름을 사용하지 마세요. 해당하는 경우 용어집에 정의된 용어를 사용하세요.

    • 예를 들어 터미널에서 명령어를 실행하는 방법에 관한 글을 작성할 때는 페이지에서 터미널과 명령줄을 모두 사용하지 마세요.

페이지 범위

  • 각 페이지에는 하나의 목적이 있어야 하며 처음부터 정의해야 합니다. 이를 통해 독자는 필요한 내용을 더 빠르게 찾을 수 있습니다.

    • : 이 페이지에서는 Windows에서 Bazel을 설치하는 방법을 설명합니다.
    • 아니요: (서론 문장이 없음)
  • 페이지 끝에서 독자에게 다음 단계를 안내합니다. 명확한 작업이 없는 페이지의 경우, 유사한 개념, 예시 또는 기타 탐색 방법을 제공하는 링크를 포함할 수 있습니다.

제목

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

  • 독자를 '나'로 지칭합니다. (어떤 이유로든 '귀하'를 사용할 수 없다면 중립적인 표현을 사용하세요.)

    • : Bazel을 사용하여 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
    • MAYBE: 사용자가 Bazel로 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
    • 아니요: Bazel로 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
  • 잠재고객이 일반적인 Bazel 사용자가 아닌 경우 페이지 시작 부분이나 섹션에서 대상을 정의합니다. 다른 잠재고객에는 관리자, 참여자, 이전자 또는 기타 역할이 포함될 수 있습니다.

  • '우리'는 피하세요. 사용자 문서에는 저자가 없습니다. 무엇이 가능한지 사람들에게 알리세요.

    • : Bazel의 발전에 따라 호환성을 유지하기 위해 코드베이스를 업데이트해야 합니다.
    • 아니요: Bazel이 진화하고 있으며 Bazel이 특정 시점과 호환되지 않는 변경사항을 Bazel 사용자에게 적용할 예정입니다.

시간적

가능하면 구체적인 날짜 (2022년 2분기)를 언급하거나 '지금', '현재' 또는 '곧'과 같이 시기적절하게 말하는 용어를 사용하지 마세요. 이러한 이미지는 빠르게 사라지고 향후 프로젝션인 경우 잘못될 수 있습니다. 대신 'Bazel X.x 이상에서 <feature> 또는 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 도움말 command: 도움말 및 '명령어' 옵션을 출력합니다.
  • 특히 복잡한 코드 샘플의 경우 상황에 맞는 자리표시자를 사용하세요.

목차

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

코드

코드 샘플은 개발자의 절친한 친구입니다. 이미 이러한 작성 방법을 알고 있을 수 있지만 몇 가지 팁을 소개합니다.

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

코드 블록

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

인라인 코드 형식 지정

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