문장 작성
이 규칙은 마크다운 문서와 모든 언어의 코드 내 doc 주석에 적용됩니다. "마크다운 전용"이라고 표시된 규칙은 doc 주석에 적용되지 않습니다. 그 영역에서 doc 주석은 해당 언어의 관례(예: Go의 [Name] doc 링크)를 따릅니다. ADR 및 용어집과 같은 특정 문서 유형을 위한 스킬은 이 규칙 위에 자체 규칙을 추가합니다.
어조
편안하지만 정확합니다. 경험 많은 엔지니어가 다른 엔지니어에게 주제를 설명하는 방식으로 작성하십시오. 지나치게 형식적인 사양 언어는 피하십시오. 기술적으로 정확하면서도 명확하고 자연스러운 설명을 선호하십시오. 어조는 접근하기 쉽고 대화체여야 하지만, 캐주얼해서는 안 됩니다.
독자가 소프트웨어 개발에 대한 중간 수준의 이해를 가지고 있지만 Dogmatiq 프로젝트나 문서의 도메인에 대해서는 알지 못할 수 있다고 가정하십시오. 전문 용어를 피하고 문서에 필요한 기술 용어는 설명하십시오. 독자를 약 5년의 전문 경력을 가진 애플리케이션 개발자로 상상하십시오. Go는 알지만 알고리즘이나 수학에 대한 배경 지식은 거의 없는 사람입니다.
파일 이름 (마크다운 전용)
LICENSE 또는 README.md와 같이 외부 규칙에서 달리 요구하지 않는 한 glossary.md와 같은 소문자 파일 이름을 사용하십시오.
줄 바꿈 (마크다운 전용)
각 단락을 다시 정렬하여 모든 줄이 80자 이내에 최대한 많은 단어를 포함하도록 하십시오.
문장 부호
- 문장에서는 곧은 따옴표와 아포스트로피(
",')를 사용하고, 둥근 따옴표는 사용하지 마십시오. 비ASCII 문자는 코드 블록과 수식에서 괜찮습니다. - 각 측면에 공백을 두고 em 대시를 작성하십시오(예:
word — word). - 괄호 구분 기호로 하이픈이 아닌 em 대시를 사용하십시오.
- 목록과 단락에서 용어를 정의하는 동격(apposition)에는 em 대시를 사용하십시오. 이 용도로 콜론, 세미콜론 또는 괄호를 사용하지 마십시오.
- em 대시가 많이 포함된 문장이나 단락을 다시 구성하는 것을 고려하십시오.
- 세미콜론은 대조(A; B는 그렇지 않음), 자격 부여(A; 그러나 B) 또는 논리적 결과(A; 따라서 B)를 위해 드물게 사용하십시오. 절(clause)이 두 개의 개별 문장으로 자연스럽게 읽히면 마침표를 선호하십시오.
- 적절한 경우 문장에서 이중 하이픈(
--)을 em 대시로 바꾸십시오. 그렇지 않으면 올바른 문장 부호를 제안하십시오.
철자
US 영어를 사용하십시오. 확실하지 않은 경우 go.dev, Go 표준 라이브러리 문서 또는 AWS 및 GCP 문서를 따르십시오.
| US (올바름) | US 아님 (틀림) |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
참조 링크 (마크다운 전용)
- 인라인 링크가 아닌 참조 스타일 링크를 사용하십시오.
- 링크 정의는 파일 하단에
<!-- references -->또는<!-- anchors -->와 같은 레이블이 지정된 HTML 주석으로 시작하는 그룹으로 배치하십시오. - 각 그룹을 레이블별로 알파벳순으로 정렬하십시오.
CHANGELOG.md의 버전 링크는 예외로, 오름차순 버전 순서(예:[0.9.0]이[0.10.0]앞에 옴)를 유지합니다. - 연결된 용어가 복수형으로 나타나면 소스가 자연스럽게 읽히도록 복수형에 대한 별도의 정의를 추가하십시오(예:
[instructions]: #instruction). - 모든 정의는 최소한 한 번 사용되어야 합니다. 사용되지 않은 정의는 제거하십시오.
- 모든 참조에는 일치하는 정의가 있어야 합니다. 끊어진 참조를 남기지 마십시오.
검토
위의 모든 규칙에 대해 텍스트를 확인하십시오. 각 문제에 대해 텍스트를 인용하고, 위반한 규칙 이름을 지정하고, 수정을 제안하십시오.