Discourse 문서화는 현재 이 스타일 가이드에 부합하도록 검토 및 편집 중입니다. 현재 모든 문서화 주제가 이 가이드에 완전히 일치하지는 않으며, 가능한 한 빨리 이를 개선하고 있습니다.
이것은 Discourse 문서화가 작성 및 서식 처리되는 방식을 안내하는 살아있는 문서(living document)로 간주됩니다. 이 주제는 필요에 따라 최신 상태로 유지됩니다. 여기 제시된 원칙 중 하나에 대해 의문이 있다면, 구체적인 사항을 논의하기 위해 해당 주제에 게시물을 작성해 주세요.
이 문서화 스타일 가이드의 핵심 원칙은 문서화를 작성할 때 독자와 그들의 요구 사항을 고려하는 것입니다 - 그들은 무엇을 성취하고자 하는가? 콘텐츠를 제공하려는 목표는 무엇인가?
스타일 가이드 적용 시 빠른 체크리스트:
메타 블록이 존재하고 정확합니다.
제목은 행동 지향적입니다.
모든 제목은 문장 대문자 규칙(sentence case)을 따릅니다.
올바른 태그와 카테고리가 사용됩니다.
문서는 논리적으로 구조화되어 있습니다.
문서 작성을 완료할 때, 이러한 모든 기준이 충족되었는지 검토하십시오.
다음 텍스트 서식 지침을 유의해 주세요:
메타 정보
문서는 다음 카테고리 중 단 하나에만 속해야 합니다:
Using Discourse
관리자가 아닌 작업을 위한 일반 사용자 가이드
Site Management
설정, 플러그인, 콘텐츠 및 일반적인 사이트 관리
Integrations
Discourse와 다른 플랫폼을 통합하는 가이드
Hosted Customers
호스팅 고객에게만 관련이 있는 가이드
Self-hosting
셀프 호스팅 사이트에のみ 관련이 있는 가이드
Developer Guides
테마, 테마 컴포넌트, 플러그인 생성을 포함하여 Discourse를 기반으로 개발하는 기술 가이드
Contributing
Discourse 오픈소스 프로젝트에 기여하는 방법 안내
문서는 다음 태그/문서 유형 중 단 하나에만 속해야 합니다:
#how-to
#explanation
#reference
#tutorial
문서는 다른 관련 태그를 가질 수 있으며, 단일 문서에 최대 5개의 태그만 사용할 수 있습니다
메타 블록
모든 문서에는 문서의 주제를 간략히 설명하는 블록과 사용자 수준 요구 사항, 콘솔 액세스 필요 여부 등 기타 관련 메타 정보가 상단에 포함되어야 합니다. 이는 제목이 없는 인용 블록(blockquote) 형식으로 서식 처리됩니다. 이것이 어떻게 보여야 하는지 예시는 다음과 같습니다:
이는 사용 가능한 모든 숨겨진 사이트 설정, 활성화 방법, 조정해야 할 이유를 설명하는 가이드입니다.
요구되는 사용자 수준: 관리자
콘솔 액세스 필요
제목 및 헤딩
문서 제목은 행동 지향적으로 작성하세요
부정확: “채팅 스레드에 대한 자동 제목 활성화 방법”
정확: “채팅 스레드에 대한 자동 제목 활성화”
문서 제목은 너무 길지 않아야 합니다
‘how-to’ 주제의 경우, 제목을 목표 지향적으로 작성하세요
모든 제목은 구체적이고 고유해야 합니다
문서 제목에는 쉼표 외의 구두점이나 특수 문자를 사용하지 마세요
문서 제목에 이모지를 포함하지 마세요
제목과 헤딩에는 문장 대문자 규칙(sentence case)을 사용하세요 - 이는 첫 번째 단어만 대문자로 시작하며, 고유명사와 일반적으로 대문자로 표기되는 다른 단어들을 포함합니다
헤딩에서 앰퍼샌드(&)를 사용하지 말고, 전체 단어(“and”)를 사용하세요
일반적인 작성 지침, 톤 및 문법
문서를 읽는 사람을 지칭할 때는 2인칭 목소리를 사용하세요 - 즉, “we” 대신 "you"를 사용하세요
가능한 한 능동 태도를 사용하세요
부정확: “버튼을 클릭해야 합니다”
정확: “버튼을 클릭하세요”
약어와 줄임말은 처음 사용할 때 정의하고, 필요하면 추가 정보를 제공하는 외부 링크를 제공하세요
짧은 문장을 사용하고, 더 짧은 단락, 헤딩, 목록을 사용하여 텍스트를 분할하세요
**굵게**와 *기울임*을 사용하여 중요한 문구나 단어를 강조할 수 있지만, 과용하지 마세요
설명 없이 전문 용어나 기술 용어를 사용하지 마세요 - 의문이 들면 설명하는 쪽으로 기울이세요
UI 요소와 같은 시각적 인터페이스를 설명할 때 스크린샷을 사용하세요
명시적으로 허용되지 않는 한, 향후 Discourse 기능, 제품 또는 서비스를 문서화하거나 공개하지 마세요
therefore(따라서), although(비록), furthermore(또한)와 같은 전이 단어(transition words)를 사용하세요.
일반적인 축약형을 사용하세요: it’s, you’ll, you’re, we’re, let’s
문서화에서는 시대를 초월하는 특성을 추론하세요 - soon(곧), new(새로운), now(지금), latest(최신) 등 빠르게 무의미해지는 단어를 피하세요
소프트웨어나 하드웨어에 인간적인 특성을 부여하지 마세요
예: “이 API에 정수를 전달하면 화를 내고 오류를 발생시킵니다”
예: “우리의 친근하고 야심 찬 AI 봇이 모든 문제를 해결해 줄 것입니다”
텍스트( Discourse UI 포함)를 인용할 때 "따옴표"를 사용하세요
URL을 인용할 때 백틱을 사용하세요
예시 도메인을 사용할 때 discourse.example.com을 사용하세요
유용하다면, 단락의 시작에 이모지를 사용하여 강조할 수 있습니다. 단일 주제에서 이러한 이모지를 두세 개 이상 사용하지 마세요. 사용할 수 있는 이모지 예시:
- 정보 노트
- 공지 또는 알림
- 경고 메시지
- 매우 중요한 정보
피해야 할 것들:
불필요한 비유나 유머
문화적 및 지역적 참조
낮추어 말하는 톤으로 절차나 지시를 하는 것 - 예: Publish 버튼을 클릭해야 합니다 또는 Publish 버튼을 클릭해야 합니다
지나치게 정중한 표현. 예: Publish 버튼을 클릭해 주세요
절대적으로 필요한 경우를 제외하고 느낌표 사용
불필요한 단어 대문자 표기
동일한 문구와 대명사의 과도한 사용
사용자 문서의 경우:
친근하고 비공식적인 톤을 유지하되, 전문적인 방식으로 명확하고 간결하게 작성하는 데 중점을 두세요. 핵심을 빠르게 전달하세요. 기술 용어를 설명하되, 낮추어 말하지 않도록 주의하세요. 명확성을 확보하기 위해 현재 주제의 맥락을 간략히 명시하는 것으로 시작하세요.
개발자 및 기술 문서의 경우:
직접적이고 정확한 톤을 유지하세요. 사용자 문서와 동일한 톤을 사용하되, 독자가 더 높은 수준의 기술 지식을 갖추고 있다고 가정할 수 있습니다.
구조
핵심을 빠르게 전달하세요 - 가장 중요한 내용으로 시작하세요
문서 초반에 중요한 키워드를 포함하세요
독자의 선택지와 다음 단계를 명확하게 보이게 하세요
문서 작성을 위해 항상 가벼운 마크업을 사용하세요 (이것은 이미 Markdown-it으로 Discourse에 내장되어 있습니다).
제목 대문자 표기(title case) 사양은 제가 정한 것입니다. 일반적으로 더 깔끔하고 전문적으로 보인다고 생각했기 때문입니다. 하지만 Google과 Microsoft 모두 문서 제목에는 문장 대문자 표기를 사용하라고 권장하고 있습니다. 제가 찾은 다른 사이트들도 문장 대문자 표기를 사용하라고 하므로, 해당 부분의 대문자 표기 요건을 되돌리고 업데이트하겠습니다.
맞습니다. 좋은 지적이네요. 그 예시는 실제 문서에서 가져온 것이었는데, 기존 문서의 제목을 사용해 해당 문서를 설명하고 있었으며, 해당 문서가 제목 대문자 표기(title case)를 사용했기 때문에 참조 부분도 그렇게 되어 있었습니다. 제목 대문자 표기에서 문장 대문자 표기(sentences case)로 변경했으므로, 해당 참조 부분도 업데이트해야 합니다.
이 부분에 대해 많은 논의가 오갔고, 스타일 가이드에 기본적으로 이 내용이 포함되었다는 것을 보고 기뻤습니다.
제가 왜 이것이 중요하다고 생각하는지 말씀드리겠습니다: 문서를 작성하는 것은 우리 커뮤니티의 가능한 많은 구성원, 특히(아마도?) 우리 Discourse 팀 구성원들이 접근할 수 있도록 해야 합니다.
Discourse는 소셜 토론 소프트웨어입니다. 그리고 일부 문서는 사실 끊임없는 대화와도 같습니다. 제 커뮤니티에 멤버를 온보딩하는 제 방식을 공유한다면, 저는 그 주제의 "소유자"로 제시되기를 원할 것입니다. 그래야 질문을 답변하고 주제를 확장할 수 있으니까요.
반면, 고객이 우리가 설명할 여유가 없었던 기능에 대해 질문한다면, 저는 스타일 가이드를 사용하여 유용하고 일반적인 문서를 작성하기를 원합니다. 주제 소유자인 것이 게시에 더 많은 관성을 부여한다고 느끼기 때문입니다.
또한, Discourse 외부에서 문서를 생성할 경우(통합이나 코드 주석에서 생성하는 등), "문서 사용자"를 가지는 것이 구현 세부 사항으로서 더 쉬울 가능성이 높습니다.
이 가이드가 사람들이 자신의 목소리와 개성을 넣고 토론을 호스팅하는 것을 막을 것이라고 생각하지는 않습니다. 하지만 그렇지 않았다면 문서화 관행에 참여하지 않았을 사람들이 더 쉽게 그 관행에 접어들도록 돕는다면 정말 좋을 것입니다(그리고 나서 더 개인적인 방향으로 유도할 수 있으니요!).
로컬라이즈된 문서를 처리하는 네이티브 방식이 도입되기 전까지는, 제목 앞에 국기(플래그)를 붙이는 것이 가장 실용적인 방법이라고 생각하며, 이 가이드라인에 대한 합리적인 예외라고 봅니다.
이런 부분은 의견과 취향이 갈릴 수 있지만, 이번 스타일 가이드에서는 업계에서 일반적으로 받아들여지는 관례를 따르기로 했습니다. 다시 한번 말씀드리자면, Google과 Microsoft 가이드라인 모두 일반적인 축약형 사용이 더 낫다고 동의하고 있습니다.
그럼에도 불구하고, 부정 축약형(예: “can’t”)을 사용하면 영어가 모국어가 아닌 사람들이 이해하는 데 더 어려울 수 있다는 게시물을 몇 가지 읽었습니다. 이 부분에 대해 더 깊이 살펴보고, 필요할 경우 스타일 가이드를 그에 맞게 업데이트하겠습니다.
해당 예시를 삭제했습니다!
네, 이것은 매우 흔한 방식입니다(단, Discourse에만 국한되지는 않음)만, 정확하지는 않다는 점에 동의합니다. 따옴표를 사용하는 것이 더 좋으므로, 스타일 가이드에서 이를 명시적으로 밝히겠습니다.
좋은 지적입니다 - 스타일 가이드에 추가하겠습니다!
이 피드백에 감사드립니다! @maiki 님이 위에서 좋은 점을 몇 가지 지적해 주셨고, 저도 그 의견에 동의합니다. 덧붙이자면, 공식 문서의 저자를 @Discourse로 변경한 이유 중 하나는 독자들, 특히 처음 문서를 방문하는 사람들에게 더 큰 권위감을 부여하기 위해서입니다. 이것이 사실 처음부터 스타일 가이드를 만든 동기이기도 합니다.
문서를 작성하는 사람은 누구나 자신의 글에 개성을 살릴 수 있으며, 개별 문서 주제에 대한 토론은 어디에도 사라지지 않을 것이므로, 그곳도 항상 더 개인적인 느낌을 살릴 수 있는 좋은 곳입니다.
가이드의 metablock 부분에 대해 말씀드리자면. 위 가이드에 따르면 Doc 토픽에는 metablock이 하나씩 필요하지만, 모든 토픽에 metablock이 있는 것은 아닙니다. [1] 또한 여기서는 일관성이 없습니다. 몇몇 가이드에서 찾은 예시를 몇 가지 올려봅니다.
또한, 새로운 정보 블록이 포함된 항목을 보게 된다면, 해당 항목은 '1단계’를 마치고 검토 단계에 들어간 상태라는 뜻입니다. 만약 읽다가 ‘이건 좀 아닌데’ 또는 '정보 누락이 있네’라고 생각하신다면, 피드백을 남겨주실 여유가 있으시다면 여러분의 생각을 게시물에 댓글로 남겨주세요.
상단에 표시되는 필수 사용자 수준 정보의 목적은 무엇인가요? 문서가 나에게 관련이 있는지 없는지를 알려줄 것이라고 생각했습니다. 그래서 읽다가 "나는 xxx가 아니니까 관련이 없네"라고 판단할 수 있을 줄 알았거든요.
하지만 실제로는 다르게 사용되는 것 같습니다. 예를 들어, TL3보다 낮은 수준의 사용자도 위키를 편집할 수 있으므로 다른 사용자들에게도 관련이 있을 수 있습니다.
Discourse 문서화는 현재 이 스타일 가이드에 부합하도록 검토 및 편집 중입니다. 현재 모든 문서화 주제가 이 가이드에 완전히 일치하지는 않으며, 가능한 한 빨리 이를 개선하고 있습니다.
스타일 가이드 적용 시 빠른 체크리스트:
이는 사용 가능한 모든 숨겨진 사이트 설정, 활성화 방법, 조정해야 할 이유를 설명하는 가이드입니다.
요구되는 사용자 수준: 관리자
콘솔 액세스 필요
- 공지 또는 알림
- 경고 메시지
- 매우 중요한 정보
가 드러나고 말 텐데 말입니다.
). 일관성 부족에 대한 지적은 좋은 의견입니다. 어떤 문서를 채택할지 아직 확신은 없지만, 반드시 하나를 정하고 그에 맞춰 일관되게 유지하겠습니다. 