스타일 가이드

스타일 가이드#

이 문서는 문서를 작성할 때 따르는 지침을 설명합니다.

작성 스타일#

명확하고 간결하게 작성하십시오#

시간이 없어서 더 짧은 편지를 쓰지 못했습니다.

— 블레즈 파스칼

독자의 시간과 주의력은 한정되어 있습니다. 이를 존중하십시오.

기여자와 유지 관리자를 대상으로 하는 소통에도 마찬가지입니다. 이 프로젝트는 공개 프로젝트이며, 여러분이 쓴 글을 많은 사람이 읽게 됩니다. 이 영향력을 신중하게 사용하십시오.

  • 근거에 기반한 쉬운 언어 지침을 따르십시오.

    • 전문 용어를 사용하지 마십시오. 독자가 특정 기술 용어에 익숙하지 않을 수 있습니다.

    • 같은 의미를 전달하는 더 짧고 간단한 단어가 있다면 길고 복잡한 단어를 사용하지 마십시오.

  • 지시 사항을 전달할 때는 명령적 어조를 사용하십시오. 예를 들어, 다음과 같이 작성하십시오.

    python310 패키지를 buildInputs에 추가하십시오.

    대화체는 내용에 대한 집중을 방해하므로 사용하지 마십시오. 예를 들어, 다음과 같이 작성하지 마십시오.

    자, 이제 이전 튜토리얼에서 본 것처럼 python310 패키지를 buildInputs에 추가해 봅시다.

포용적인 언어를 사용하십시오#

Contributor Covenant(기여자 서약)과 The Carpentries Code of Conduct에서 가져와 수정한 내용입니다:

  • 환영하고 포용하는 언어를 사용하십시오

  • 다른 사람에게 공감과 존중을 보이십시오

  • 다양한 관점과 경험을 존중하십시오

  • 건설적인 비판을 건네고, 받을 때는 너그럽게 받아들이십시오

  • 커뮤니티에 가장 좋은 것에 집중하십시오

관용구는 영어를 모국어로 쓰지 않는 사람이 이해하기 어려울 수 있으므로 피하십시오.

재미있게 쓰려고 하지 마십시오. 유머는 문화에 따라 매우 다르게 받아들여집니다. 잘해야 농담은 관련 지시 사항을 흐릴 뿐입니다. 최악의 경우 농담은 독자의 기분을 상하게 하고, 독자의 학습을 도우려는 우리의 노력을 헛되게 만들 수 있습니다.

대중문화를 인용하지 마십시오. 여러분이 잘 알려져 있다고 생각하는 것도 배경이 다른 사람들에게는 전혀 생소하고 주의를 흐트러뜨릴 수 있습니다.

어조#

주제를 사실에 근거하여 설명하고, 직접적인 지시에는 명령적 어조를 사용하십시오.

독자와 개인적인 관계를 전제하지 말고, 감정에 호소하기보다 명확성과 간결성을 우선하십시오.

독자를 가리킬 때는 “여러분”을 사용하고, “우리”는 저자를 가리킬 때만 사용하십시오. 두 표현 모두 필요한 경우는 드물어야 합니다.

예를 들면 다음과 같습니다:

원격 머신에 시크릿을 배포해야 합니다. 여기서는 scp를 사용하는 명시적인 수동 절차를 보여 주기로 했지만, 이를 자동화하는 다양한 도구가 있습니다.

정확하게 작성하고 출처를 밝히십시오#

문서가 없는 것보다 더 나쁜 것은 잘못된 문서뿐입니다. 정확성을 보장하는 한 가지 방법은 출처를 밝히는 것입니다. 어떤 것이 동작하는 방식에 대해 주장한다면(예: 어떤 명령줄 인수가 존재한다는 것), 해당 주제의 공식 문서에 링크하십시오. 우리는 문서 간의 연결망을 유지하고자 하므로, 다른 문서에 링크하면 문서 생태계를 강화하는 데 도움이 됩니다.

전반적인 경험을 개선하기 위해 적절한 경우 매뉴얼을 업데이트하거나 재구성하는 것을 명시적으로 권장합니다.

마크업과 소스#

코드 예제#

코드를 보여 주기 전에 항상 그 코드가 무엇을 위한 것인지 또는 무엇을 하는지 글로 설명하여 코드의 필요성을 먼저 제시하십시오.

반례

Run this command:

```bash
:(){ :|:& };:
```

간단하지 않은 예제는 추가 설명이 필요할 수 있으며, 특히 주어진 맥락 밖의 개념을 사용하는 경우에 그렇습니다. 읽는 흐름을 방해할 수 있는 설명에는 접힌 콘텐츠 상자를 사용하십시오.

예시

Set off a [fork bomb](https://en.wikipedia.org/wiki/Fork_bomb):

```bash
:(){ :|:& };:
```

:::{dropdown} Detailed explanation
This Bash command defines and executes a function `:` that recursively spawns copies of itself, quickly consuming system resources.
:::

코드는 항상 본문에서 설명하십시오. 코드 예제에서 주석은 특정 측면을 강조할 때처럼 매우 드물게 사용하십시오.

독자는 정보를 찾으려고 훑어볼 때 많은 양의 코드를 대충 넘기는 경향이 있으며, 그 대부분이 주석이더라도 마찬가지입니다. 특히 초보자는 더 복잡해 보이는 코드를 읽기 힘들어할 가능성이 높으며, 그래서 아예 읽지 않을 수도 있습니다.

코드 예제에 인라인 설명이 많이 필요해 보인다면 더 간단한 예제로 바꾸는 것을 고려하십시오. 그것이 불가능하다면 예제를 여러 부분으로 나누어 각각 설명한 다음, 마지막에 합친 결과를 보여 주십시오.

동작하도록 의도한 코드 예제는 실제로 동작해야 합니다.

동작하지 않는 예제를 제시하려는 경우(예: 흔한 실수를 보여 주는 경우) 이를 미리 설명하십시오. 많은 독자는 그 코드가 동작하도록 의도된 것이 아니라는 사실을 미리 읽어 확인하지 않은 채, 예제 코드를 동작시키려다 막히게 됩니다.

모든 코드 예제에는 렌더링할 때 구문 강조가 적용되도록, 해당하는 경우 프로그래밍 언어를 명시해야 합니다. 예:

```python
print("Hello, World!")
```

제목#

가장 큰 제목(#)은 문서 제목에만 사용하십시오.

문서 본문의 내용을 나눌 때는 Markdown 제목 ##부터 ###까지를 사용하십시오. 제목을 더 세분화한다고 해서 반드시 더 좋은 것은 아닙니다.

한 줄에 한 문장#

한 줄에 한 문장씩 작성하십시오.

이렇게 하면 긴 문장이 바로 눈에 띕니다. 또한 GitHub 리뷰 인터페이스는 줄 단위로 동작하므로 변경 사항을 검토하고 직접 제안을 달기도 쉬워집니다.