# 스타일 가이드 이 문서는 문서를 작성할 때 따르는 지침을 설명합니다. ## 작성 스타일 ### 명확하고 간결하게 작성하십시오 > 시간이 없어서 더 짧은 편지를 쓰지 못했습니다. > > — [블레즈 파스칼](https://en.m.wikiquote.org/w/index.php?title=Blaise_Pascal&oldid=2978584#Quotes) 독자의 시간과 주의력은 한정되어 있습니다. 이를 존중하십시오. 기여자와 유지 관리자를 대상으로 하는 소통에도 마찬가지입니다. 이 프로젝트는 공개 프로젝트이며, 여러분이 쓴 글을 많은 사람이 읽게 됩니다. 이 영향력을 신중하게 사용하십시오. - 근거에 기반한 [쉬운 언어 지침](https://www.plainlanguage.gov/guidelines/)을 따르십시오. - 전문 용어를 사용하지 마십시오. 독자가 특정 기술 용어에 익숙하지 않을 수 있습니다. - 같은 의미를 전달하는 더 짧고 간단한 단어가 있다면 길고 복잡한 단어를 사용하지 마십시오. - 지시 사항을 전달할 때는 명령적 어조를 사용하십시오. 예를 들어, 다음과 같이 작성하십시오. > `python310` 패키지를 `buildInputs`에 추가하십시오. 대화체는 내용에 대한 집중을 방해하므로 사용하지 마십시오. 예를 들어, 다음과 같이 작성하지 마십시오. > 자, 이제 이전 튜토리얼에서 본 것처럼 `python310` 패키지를 `buildInputs`에 추가해 봅시다. ### 포용적인 언어를 사용하십시오 [Contributor Covenant(기여자 서약)][Contributor Covenant]과 [The Carpentries Code of Conduct]에서 가져와 수정한 내용입니다: - 환영하고 포용하는 언어를 사용하십시오 - 다른 사람에게 공감과 존중을 보이십시오 - 다양한 관점과 경험을 존중하십시오 - 건설적인 비판을 건네고, 받을 때는 너그럽게 받아들이십시오 - 커뮤니티에 가장 좋은 것에 집중하십시오 관용구는 영어를 모국어로 쓰지 않는 사람이 이해하기 어려울 수 있으므로 피하십시오. 재미있게 쓰려고 하지 마십시오. 유머는 문화에 따라 매우 다르게 받아들여집니다. 잘해야 농담은 관련 지시 사항을 흐릴 뿐입니다. 최악의 경우 농담은 독자의 기분을 상하게 하고, 독자의 학습을 도우려는 우리의 노력을 헛되게 만들 수 있습니다. 대중문화를 인용하지 마십시오. 여러분이 잘 알려져 있다고 생각하는 것도 배경이 다른 사람들에게는 전혀 생소하고 주의를 흐트러뜨릴 수 있습니다. [Contributor Covenant]: https://github.com/EthicalSource/contributor_covenant/blob/cd7fcf684249786b7f7d47ba49c23a6bcb3233eb/content/version/2/1/code_of_conduct.md [The Carpentries Code of Conduct]: https://github.com/carpentries/docs.carpentries.org/blob/fb188fa8d7f57ad85eb525091e335ed0d8fea16d/source/policies/coc/index.md#L13-L19 ### 어조 주제를 사실에 근거하여 설명하고, 직접적인 지시에는 명령적 어조를 사용하십시오. 독자와 개인적인 관계를 전제하지 말고, 감정에 호소하기보다 명확성과 간결성을 우선하십시오. 독자를 가리킬 때는 "여러분"을 사용하고, "우리"는 저자를 가리킬 때만 사용하십시오. 두 표현 모두 필요한 경우는 드물어야 합니다. 예를 들면 다음과 같습니다: > 원격 머신에 시크릿을 배포해야 합니다. 여기서는 `scp`를 사용하는 명시적인 수동 절차를 보여 주기로 했지만, 이를 자동화하는 다양한 도구가 있습니다. ### 정확하게 작성하고 출처를 밝히십시오 문서가 없는 것보다 더 나쁜 것은 *잘못된 문서*뿐입니다. 정확성을 보장하는 한 가지 방법은 출처를 밝히는 것입니다. 어떤 것이 동작하는 방식에 대해 주장한다면(예: 어떤 명령줄 인수가 존재한다는 것), 해당 주제의 공식 문서에 링크하십시오. 우리는 문서 간의 연결망을 유지하고자 하므로, 다른 문서에 링크하면 문서 생태계를 강화하는 데 도움이 됩니다. 전반적인 경험을 개선하기 위해 적절한 경우 매뉴얼을 업데이트하거나 재구성하는 것을 명시적으로 권장합니다. ## 마크업과 소스 ### 코드 예제 코드를 보여 주기 전에 항상 그 코드가 무엇을 위한 것인지 또는 무엇을 하는지 글로 설명하여 코드의 필요성을 먼저 제시하십시오. ::::{admonition} 반례 :class: error ````markdown Run this command: ```bash :(){ :|:& };: ``` ```` :::: 간단하지 않은 예제는 추가 설명이 필요할 수 있으며, 특히 주어진 맥락 밖의 개념을 사용하는 경우에 그렇습니다. 읽는 흐름을 방해할 수 있는 설명에는 접힌 콘텐츠 상자를 사용하십시오. ::::{admonition} 예시 :class: tip ````markdown 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 리뷰 인터페이스는 줄 단위로 동작하므로 변경 사항을 검토하고 직접 제안을 달기도 쉬워집니다. ### 링크 소스의 가독성을 높이려면 [참조 링크](https://github.github.com/gfm/#reference-link)를 사용하되, 꼭 필요한 곳에만 절제해서 사용하십시오. 링크 정의는 처음 사용하는 곳 가까이에 두십시오. :::{admonition} 예시 :class: tip ```markdown We follow the [Diátaxis](https://diataxis.fr/) approach to structure documentation. This framework distinguishes between [tutorials], [guides], [reference], and [explanation]. [tutorials]: https://diataxis.fr/tutorials/ [guides]: https://diataxis.fr/how-to-guides/ [reference]: https://diataxis.fr/reference/ [explanation]: https://diataxis.fr/explanation/ ``` ::: 외부 자료의 최신 버전을 가리켜야 한다는 명시적인 요구가 없다면, 모든 참조는 [영구 링크](https://en.wikipedia.org/wiki/Permalink)여야 합니다. 많은 웹 서비스가 영구 링크를 제공합니다. 예를 들면 다음과 같습니다. - [특정 커밋을 가리키는 GitHub URL](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files) - [특정 페이지 버전을 가리키는 Wikipedia URL](https://en.wikipedia.org/wiki/Wikipedia:Linking_to_Wikipedia#Permanent_links_to_old_versions_of_pages) - [웹 페이지를 영구 보존하기 위한 Internet Archive "Save Page Now"](https://web.archive.org/save)