Bazel 문서에 기여해 주셔서 감사합니다. 이 문서는 시작하는 데 도움이 되는 간단한 문서 스타일 가이드입니다. 이 가이드에서 답변하지 않는 스타일 관련 질문은 Google 개발자 문서 스타일 가이드를 따르세요.
원칙 정의
Bazel 문서는 다음 원칙을 준수해야 합니다.
- 간결함. 가능한 한 적은 단어를 사용합니다.
- 명확함. 쉬운 언어를 사용합니다. 5학년 읽기 수준에 맞춰 전문 용어를 사용하지 않고 작성합니다.
- 일관성. 문서 전체에서 반복되는 개념에 동일한 단어나 구문을 사용합니다.
- 정확함. 시간 기반 정보와 미래에 대한 약속을 피하여 콘텐츠가 최대한 오랫동안 정확하게 유지되도록 작성합니다.
쓰기
이 섹션에는 기본적인 작성 도움말이 포함되어 있습니다.
제목
- 페이지 수준 제목은 H2부터 시작합니다. (H1 제목은 페이지 제목으로 사용됩니다.)
헤더는 적절한 수준에서 최대한 짧게 만듭니다. 이렇게 하면 줄바꿈 없이 목차에 맞게 표시됩니다.
- 좋은 예: 권한
- 나쁜 예: 권한에 관한 간단한 참고사항
제목에는 문장 첫 글자를 대문자로 표기하는 규칙을 사용합니다.
- 좋은 예: 작업공간 설정
- 나쁜 예: 작업공간 설정
제목은 작업 기반 또는 실행 가능한 제목으로 만듭니다. 제목이 개념적인 경우 이해를 기반으로 할 수 있지만 사용자가 수행하는 작업을 작성합니다.
- 좋은 예: 그래프 순서 유지
- 나쁜 예: 그래프 순서 유지
이름
Bazel 및 Starlark와 같은 고유 명사에는 대문자를 사용합니다.
- 좋은 예: 빌드가 끝나면 Bazel이 요청된 대상을 출력합니다.
- 나쁜 예: 빌드가 끝나면 bazel이 요청된 대상을 출력합니다.
일관성을 유지해야 합니다. 기존 개념에 새로운 이름을 도입하지 마세요. 해당하는 경우 용어집에 정의된 용어를 사용합니다.
- 예를 들어 터미널에서 명령어 실행에 관해 작성하는 경우 페이지에서 터미널과 명령줄을 모두 사용하지 마세요.
페이지 범위
각 페이지에는 하나의 목적이 있어야 하며 이 목적은 시작 부분에 정의되어야 합니다. 이렇게 하면 독자가 필요한 내용을 더 빠르게 찾을 수 있습니다.
- 좋은 예: 이 페이지에서는 Windows에 Bazel을 설치하는 방법을 설명합니다.
- 나쁜 예: (소개 문장이 없음)
페이지 끝에 독자가 다음에 해야 할 일을 알려줍니다. 명확한 작업이 없는 페이지의 경우 유사한 개념, 예시 또는 기타 탐색 방법으로 연결되는 링크를 포함할 수 있습니다.
제목
Bazel 문서에서 잠재고객은 주로 사용자, 즉 Bazel을 사용하여 소프트웨어를 빌드하는 사람들이어야 합니다.
독자를 '사용자'라고 부릅니다. (어떤 이유로 '사용자'를 사용할 수 없는 경우 '그들'과 같은 성 중립적인 언어를 사용합니다.)
- 좋은 예: Bazel을 사용하여 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
- MAYBE: 사용자가 Bazel로 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
- 나쁜 예: 사용자가 Bazel로 Java 코드를 빌드하려면 JDK를 설치해야 합니다.
잠재고객이 일반적인 Bazel 사용자가 아닌 경우 페이지 또는 섹션의 시작 부분에 잠재고객을 정의합니다. 기타 잠재고객에는 유지관리자, 기여자, 이전자 또는 기타 역할이 포함될 수 있습니다.
'우리'는 사용하지 마세요. 사용자 문서에는 작성자가 없습니다. 가능한 작업을 사용자에게 알려주기만 하면 됩니다.
- 좋은 예: Bazel이 발전함에 따라 호환성을 유지하려면 코드베이스를 업데이트해야 합니다.
- 나쁜 예: Bazel이 발전하고 있으며 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 설치]를 참고하세요.
- 나쁜 예: 자세한 내용은 [여기]를 참고하세요.
가능한 경우 링크로 문장을 끝냅니다.
- 좋은 예: 자세한 내용은 [링크]를 참고하세요.
- 나쁜 예: 자세한 내용은 [링크] 를 참고하세요.
목록
- 순서가 지정된 목록을 사용하여 단계별로 작업을 완료하는 방법을 설명합니다.
- 순서가 지정되지 않은 목록을 사용하여 작업 기반이 아닌 항목을 나열합니다. (알파벳순, 중요도 등과 같은 순서가 있어야 합니다.)
- 병렬 구조로 작성합니다. 예를 들면 다음과 같습니다.
- 모든 목록 항목을 문장으로 만듭니다.
- 동일한 시제의 동사로 시작합니다.
- 따라야 할 단계가 있는 경우 순서가 지정된 목록을 사용합니다.
자리표시자
사용자가 변경해야 하는 변수를 나타내려면 꺾쇠괄호를 사용합니다. 마크다운에서 백슬래시(
\<example\>)로 꺾쇠괄호를 이스케이프 처리합니다.- 예:
bazel help <command>: 도움말 및 옵션을 출력합니다.<command> - 나쁜 예: bazel help command: 도움말 및 'command'의 옵션을 출력합니다.
- 예:
특히 복잡한 코드 샘플의 경우 컨텍스트에서 의미가 있는 자리표시자를 사용합니다.
목차
사이트에서 지원하는 자동 생성된 목차를 사용합니다. 수동 목차를 추가하지 마세요.
코드
코드 샘플은 개발자에게 유용한 도구입니다. 이미 작성 방법을 알고 계시겠지만 몇 가지 도움말을 소개합니다.
작은 코드 스니펫을 참조하는 경우 문장에 삽입할 수 있습니다. 독자가 명령어를 복사하는 등 코드를 사용하도록 하려면 코드 블록을 사용합니다.
코드 블록
- 간략하게 만듭니다. 코드 샘플에서 중복되거나 불필요한 텍스트를 모두 삭제합니다.
- 마크다운에서 샘플의 언어를 추가하여 코드 블록의 유형을 지정합니다.
```shell
...
- 명령어와 출력을 서로 다른 코드 블록으로 구분합니다.
인라인 코드 형식
- 파일 이름, 디렉터리, 경로, 작은 코드 조각에는 코드 스타일을 사용합니다.
- _기울임꼴_, "따옴표" 또는 **굵게** 대신 인라인 코드 스타일을 사용합니다.
- 예:
bazel help <command>: 도움말 및 옵션을 출력합니다.<command> - 나쁜 예: bazel help command: 도움말 및 'command'의 옵션을 출력합니다.
- 예: