Bazel 문서에 참여해 주셔서 감사합니다. 이렇게 하면 문서 스타일 가이드를 참고하세요. 스타일에 관한 질문이 있는 경우 자세한 내용은 Google 개발자 문서 스타일 가이드
원칙 정의
Bazel 문서는 다음과 같은 원칙을 준수해야 합니다.
- 간결함. 가능한 한 적은 단어를 사용합니다.
- 명확함. 쉬운 표현 사용 5학년을 위해 전문 용어 없이 작성하기 확인할 수 있습니다.
- 일관성. 반복되는 개념에 동일한 단어나 문구를 사용합니다. 확인할 수 있습니다
- 정답입니다. 미래에 대한 약속을 피하는 것이 중요합니다.
쓰기
이 섹션에는 기본적인 작성 팁이 포함되어 있습니다.
제목
- 페이지 수준 제목은 H2에서 시작합니다. H1 제목은 페이지 제목으로 사용됩니다.
헤더를 가능한 한 짧게 만드세요. 이렇게 하면 TOC에 맞추어 할 수 있습니다.
- 예: 권한
- 아니요: 권한에 대한 간단한 참고사항입니다.
제목에 문장 첫 글자 대문자 사용
- 예: 작업공간을 설정합니다.
- 아니요: 작업공간 설정하기
제목은 작업에 기반하거나 실행 가능한 것으로 설정하세요. 제목이 개념적이라면 이해에 기반할 수 있지만 사용자가 하는 일에 대해 작성합니다.
- 예: 그래프 순서 유지
- 아니요: 그래프 순서 보존
이름
고유 명사(예: Bazel 및 Starlark)를 대문자로 표기합니다.
- Yes: 빌드가 끝나면 Bazel이 요청된 대상을 출력합니다.
- 아니요: 빌드가 끝나면 bazel이 요청된 대상을 출력합니다.
일관성을 유지하세요. 기존 개념에 새 이름을 도입하지 마세요. 위치 해당되는 경우 용어집.
- 예를 들어, 로컬 컴퓨터에 대한 명령을 실행하는 것에 대해 페이지에서 터미널과 명령줄을 모두 사용하지 마세요.
페이지 범위
각 페이지에는 하나의 목적이 있어야 하며 시작하겠습니다 이렇게 하면 독자가 필요한 것을 더 빠르게 찾을 수 있습니다.
- 예: 이 페이지에서는 Windows에 Bazel을 설치하는 방법을 설명합니다.
- 아니요: (서문이 없습니다.)
페이지의 마지막 부분에서 다음에 할 작업을 안내합니다. 페이지 명확한 행동이 없으며, 유사한 개념에 대한 링크를 포함할 수 있습니다. 예, 아니면 다른 탐색 방법을 소개해야 합니다
제목
Bazel 문서에서 대상은 주로 사용자, 즉 Bazel을 사용하여 소프트웨어를 빌드할 수 있습니다
독자를 '나'라고 지칭하세요. (어떤 이유로든 '귀하'를 사용할 수 없는 경우 등의 성 중립적인 표현을 사용합니다.)
- 예: Bazel을 사용하여 Java 코드를 빌드하려면 다음 단계를 따르세요. JDK를 설치해야 합니다.
- MAYBE: 사용자가 Bazel을 사용하여 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
- 아니요: 사용자가 다음을 사용하여 Java 코드를 빌드합니다. 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를 시작하고 빌드할 수 있습니다
- 아니요: X가 Bazel에 의해 시작된 경우 이후 Y는 출력으로 빌드됩니다.
분위기
비즈니스 친화적 어조로 작성해 줘.
구어적 표현은 피합니다. 영어 문장을 번역하는 것은 있습니다.
- 예: 규칙 집합이 양호함
- 아니요: 그렇다면 좋은 규칙 집합이란 무엇일까요?
지나치게 격식을 차린 표현을 피합니다. 직책을 설명하는 것처럼 작성하세요. 테크에 대해 호기심이 있지만 세부 사항은 모르는 사람에게 제안할 수 있습니다.
형식 지정
파일 형식
가독성을 위해 줄을 80자(영문 기준)로 래핑합니다. 긴 링크 또는 코드 스니펫 더 길 수 있지만 새로운 줄에서 시작해야 합니다. 예를 들면 다음과 같습니다.
링크
'여기' 대신 설명하는 링크 텍스트를 사용하세요. 또는 '아래'로 표시됩니다. 이 관행 문서를 더 쉽게 스캔할 수 있으며 스크린 리더에 더 적합합니다.
- 예: 자세한 내용은 [Bazel 설치]를 참고하세요.
- 아니요: 자세한 내용은 [여기]를 참고하세요.
가능하다면 링크로 문장을 마무리하세요.
- 예: 자세한 내용은 [링크]를 참고하세요.
- 아니요: [링크] 에서 자세한 내용을 확인하세요.
목록
- 순서가 지정된 목록을 사용하여 단계별 작업 수행 방법 설명
- 정렬되지 않은 목록을 사용하여 작업 기반이 아닌 항목을 나열합니다. (고객 일치 타겟팅의 알파벳순, 중요도 등 정렬 순서일 수 있습니다.)
- 병렬 구조로 쓰기 예를 들면 다음과 같습니다.
- 모든 목록 항목을 문장으로 만듭니다.
- 같은 시제의 동사부터 시작합니다.
- 따라야 할 단계가 있다면 순서가 지정된 목록을 사용합니다.
자리표시자
사용자가 변경해야 하는 변수를 표시하려면 꺾쇠괄호를 사용합니다. 마크다운에서 꺾쇠괄호를 백슬래시로 이스케이프 처리합니다(예:
\<example\>).- 예:
bazel help <command>: 인쇄<command>도움말 및 옵션 - 아니요: bazel help 명령어: 도움말을 출력합니다. '명령어' 옵션이 있습니다
- 예:
특히 복잡한 코드 샘플의 경우 적절한 자리표시자를 사용하세요. 더 잘 이해할 수 있습니다
목차
사이트에서 지원하는 자동 생성 TOC를 사용합니다. 수동 TOC를 추가하지 마세요.
코드
코드 샘플은 가장 친한 친구. 여러분은 아마도 이런 질문을 작성하는 방법을 하지만 몇 가지 팁을 알려드리겠습니다.
작은 코드 스니펫을 참조하는 경우 문장 안에 삽입할 수 있습니다. 리더에서 명령어 복사와 같이 코드를 사용하도록 하려면 차단될 수 있습니다.
코드 블록
- 간략하게 만듭니다. 코드에서 중복되거나 불필요한 모든 텍스트 제거 샘플입니다.
- 마크다운에서 샘플 언어를 추가하여 코드 블록 유형을 지정합니다.
```shell
...
- 명령어와 출력을 서로 다른 코드 블록으로 구분합니다.
인라인 코드 형식 지정
- 파일 이름, 디렉터리, 경로, 코드의 작은 부분에 코드 스타일을 사용하세요.
- 기울임꼴, '따옴표' 대신 인라인 코드 스타일을 사용하세요. 또는 굵은 글씨로 표시할 수도 있습니다.
- 예:
bazel help <command>: 인쇄<command>도움말 및 옵션 - 아니요: bazel help 명령어: 도움말을 출력합니다. '명령어' 옵션이 있습니다
- 예: