이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Bazel 문서 스타일 가이드

Bazel 문서에 참여해 주셔서 감사합니다. 이 가이드는 시작하는 데 도움이 되는 간단한 문서 스타일 가이드 역할을 합니다. 이 가이드에서 답을 찾을 수 없는 스타일 관련 질문은 Google 개발자 문서 스타일 가이드를 따르세요.

원칙 정의

Bazel 문서는 다음 원칙을 유지해야 합니다.

간결하게. 최대한 적은 수의 단어를 사용합니다.
삭제. 쉬운 표현을 사용합니다. 5학년 독해 수준에 맞게 전문 용어 없이 작성합니다
일관성. 문서 전체에서 반복되는 개념에 동일한 단어나 구문을 사용하세요.
정답입니다. 시간 기반 정보와 미래에 대한 약속을 지양하여 콘텐츠가 최대한 오래 올바르게 유지되는 방식으로 작성합니다.

쓰기

이 섹션에는 기본적인 글쓰기 팁이 포함되어 있습니다.

제목

페이지 수준 제목은 H2에서 시작합니다. (H1 제목은 페이지 제목으로 사용됩니다.)
적절한 경우 헤더를 최대한 짧게 작성합니다. 이렇게 하면 래핑하지 않고 TOC에 맞습니다.
- 예: 권한
- 아니요: 권한에 관한 간단한 참고사항
제목에 문장 첫 글자 대문자 사용
- 예: 작업공간을 설정합니다.
- 아니요: 작업공간을 설정합니다.
제목은 작업 기반이거나 실행 가능한 제목을 만듭니다. 제목이 개념이라면, 이해를 바탕으로 할 수도 있지만 사용자가 하는 일에 따라 쓰도록 해야 합니다.
- 예: 그래프 순서를 유지합니다.
- 아니요: 그래프 순서 보존

이름

Bazel 및 Starlark와 같은 고유 명사는 대문자로 표기합니다.
- Yes: 빌드가 끝나면 Bazel이 요청된 대상을 출력합니다.
- 아니요: 빌드가 끝나면 bazel이 요청된 대상을 출력합니다.
일관성을 유지하세요. 기존 개념에 새로운 이름을 도입하지 않습니다. 해당하는 경우 용어집에 정의된 용어를 사용하세요.
- 예를 들어 터미널에서 명령어 실행에 관한 내용을 작성하는 경우 페이지에서 터미널과 명령줄을 모두 사용하지 마세요.

페이지 범위

각 페이지에는 하나의 목적이 있어야 하며 그러한 목적이 있어야 합니다. 이렇게 하면 독자가 필요한 정보를 더 빠르게 찾을 수 있습니다.
- 예: 이 페이지에서는 Windows에 Bazel을 설치하는 방법을 설명합니다.
- 아니요: (소개 문장을 사용하지 않음)
페이지 끝에서 독자에게 다음 단계를 알려줍니다. 명확한 작업이 없는 페이지의 경우 유사한 개념, 예시 또는 기타 탐색 방법으로 연결되는 링크를 포함할 수 있습니다.

제목

Bazel 문서에서 대상은 주로 사용자여야 합니다. 즉, Bazel을 사용하여 소프트웨어를 빌드하는 사람입니다.

리더를 '나'로 지칭합니다. (어떤 이유로든 '여러분'을 사용할 수 없다면 성 중립적 표현을 사용하세요.)
- 예: Bazel을 사용하여 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
- 가능성: 사용자가 Bazel을 사용하여 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
- 아니요: 사용자가 Bazel을 사용하여 자바 코드를 빌드하려면 JDK를 설치해야 합니다.
잠재고객이 일반 Bazel 사용자가 아닌 경우 페이지의 시작 부분이나 섹션에서 잠재고객을 정의합니다. 다른 잠재고객에는 유지관리 담당자, 참여자, 마이그레이션자 또는 기타 역할이 포함될 수 있습니다.
'우리'를 피합니다. 사용자 문서에는 작성자가 없으며 가능한 작업만 알려주세요.
- 예: Bazel이 발전함에 따라 호환성을 유지하도록 코드베이스를 업데이트해야 합니다.
- 아니요: Bazel은 발전하고 있으며, 때로는 Bazel을 변경할 예정입니다. 이러한 변경은 때에 따라 호환되지 않고 Bazel 사용자가 변경해야 하는 것입니다.

시간

가능한 경우 특정 날짜 (2022년 2분기)를 언급하거나 '지금', '현재', '곧'과 같이 시간을 뜻하는 표현을 사용하지 않습니다. 이는 빠르게 비활성화되며 향후 프로젝션인 경우 정확하지 않을 수 있습니다. 대신 'Bazel X.x 이상에서 <feature>를 지원하거나 GitHub 문제 링크를 지원합니다.

예: Bazel 0.10.0 이상에서는 원격 캐싱을 지원합니다.
아니요: Bazel은 곧 원격 캐싱을 지원할 예정입니다(2017년 10월 예정).

긴장감 있는 음악

현재 시제를 사용합니다. 명확성을 위해 꼭 필요한 경우가 아니라면 과거 또는 미래형은 사용하지 않습니다.
- Yes: Bazel은 이 규칙을 준수하지 않는 종속 항목을 발견하면 오류를 발생시킵니다.
- 아니요: Bazel이 이 규칙을 준수하지 않는 종속 항목을 발견하면 Bazel이 오류를 발생시킵니다.
가능하다면 수동태 (대상이 객체를 대상으로 하는 경우)가 아닌 능동형 (주체가 객체에 대해 동작하는 경우)을 사용하세요. 일반적으로 능동태는 누가 책임을 지는지 보여주기 때문에 문장을 더 명확하게 만듭니다. 능동태 사용으로 인해 명확성이 저하되는 경우 수동태를 사용합니다.
- 예: Bazel이 X를 시작하고 출력을 사용하여 Y를 빌드합니다.
- 아니요: X가 Bazel에 의해 시작된 후 Y가 출력과 함께 빌드됩니다.

분위기

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

구어체 표현은 피합니다. 영어와 관련된 구문은 번역하기가 더 어렵습니다.
- 예: 적합한 규칙 세트
- 아니요: 좋은 규칙 세트란 무엇일까요?
지나치게 공식적인 표현은 피합니다. 기술에 호기심이 있지만 자세한 내용은 모르는 사람에게 개념을 설명하는 것처럼 이메일을 작성합니다.

형식 지정

파일 형식

가독성을 위해 줄을 80자(영문 기준)로 래핑합니다. 긴 링크나 코드 스니펫은 더 길 수 있지만 새로운 줄에서 시작해야 합니다. 예를 들면 다음과 같습니다.

링크

'여기' 또는 '아래' 대신 설명적인 링크 텍스트를 사용하세요. 이렇게 하면 문서를 더 쉽게 스캔할 수 있으며 스크린 리더에 더 적합합니다.
- 예: 자세한 내용은 [Bazel 설치]를 참고하세요.
- 아니요: 자세한 내용은 [여기]를 참고하세요.
가능하다면 링크로 문장을 끝냅니다.
- 예: 자세한 내용은 [link]를 참고하세요.
- 아니요: 자세한 내용은 [링크] 를 참고하세요.

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

자리표시자

꺾쇠괄호를 사용하여 사용자가 변경해야 하는 변수를 표시합니다. 마크다운에서 꺾쇠괄호를 백슬래시로 이스케이프합니다(\<example\>).
- 예: bazel help <command>: <command>의 도움말 및 옵션을 출력합니다.
- 아니요: bazel 도움말 명령어: '명령어'의 도움말 및 옵션을 출력합니다.
특히 복잡한 코드 샘플의 경우 컨텍스트에 맞는 자리표시자를 사용합니다.

코드

코드 샘플은 개발자에게 가장 좋은 방법입니다. 작성 방법을 이미 알고 있겠지만 몇 가지 팁이 있습니다

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

코드 블록

간략하게 만듭니다. 코드 샘플에서 중복되거나 불필요한 텍스트를 모두 제거합니다.
마크다운에서 샘플 언어를 추가하여 코드 블록 유형을 지정합니다.

```shell
...

명령어와 출력을 서로 다른 코드 블록으로 분리합니다.

인라인 코드 형식 지정

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