이 가이드는 Discourse에 효과적인 how-to(단계별 안내) 문서를 작성하는 방법에 대한 지침을 제공합니다. 구조와 스타일, 대상 독자 고려, 유지 관리 등 필수 요소를 다룹니다.
필요한 사용자 권한: 누구나 새로운 how-to 가이드를 작성할 수 있습니다
효과적인 how-to 문서를 작성하는 것은 사용자가, модератор, 관리자, 시스템 관리자가 Discourse 내에서 다양한 작업을 수행하도록 돕는 데 매우 중요합니다. 이 가이드를 통해 커뮤니티를 위해 명확하고 가치 있는 how-to 가이드를 작성하는 데 도움이 됩니다.
요약
이 문서에서는 다음 내용을 배울 수 있습니다:
- how-to 작성의 중요성
- 포함해야 할 정보
- 구조와 스타일 지침
- 해당 주제를 게시할 위치
- 게시 후 유지 관리 방법
왜 how-to를 작성해야 하는가?
어떤 작업을 수행해야 하는데 방법을 기억하지 못한 경험이 있으신가요? how-to 문서를 작성하는 것은 Discourse의 프로세스를 문서화하는 훌륭한 방법입니다. 특정 프로세스에서 어려움을 겪고 있다면, 다른 사람들도 마찬가지일 가능성이 높습니다. 이를 문서화하면 모두에게 도움이 됩니다.
how-to가 튜토리얼이나 참고 자료와 같은 다른 유형의 문서와 어떻게 다른지 알아보려면 Divio의 이 가이드를 확인하세요.
how-to를 작성하거나 검토하는 것은 Discourse에 대한 지식을 커뮤니티에 기여하기 시작하는 훌륭한 방법입니다. 다른 기여 방법에 대해서는 Discourse에 기여하는 방법 가이드를 확인하세요.
어떤 정보를 포함해야 하는가?
how-to는 사용자를 특정 최종 결과로 이끌어내는 단계별 안내서여야 합니다. 예를 들어, "Discourse에 HTTPS 설정"이라는 제목의 how-to는 HTTPS를 설정하는 방법을 설명해야 합니다.
how-to 가이드를 작성할 때 기억해야 할 주요 사항:
- 주제에 집중하고 명확하게 작성하세요
- 불필요한 정보는 피하세요
- 간결하면서도 정보량이 풍부해야 합니다
- 최종 결과를 달성하는 것이 왜 이로운지 왜를 설명하세요
대상 독자를 고려하세요
Discourse how-to에는 다양한 대상 독자가 있으며, 각각 다른 수준의 설명이 필요합니다. 문서 카테고리를 가이드로 사용하여 가이드의 대상 독자를 결정하세요:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
대상 독자의 기술 수준을 이해하고 그에 맞게 가이드를 조정하세요. 몇 가지 팁:
- 독자가 수행할 수 없는 단계는 피하세요 (예: 호스팅 고객은 일반적으로 콘솔 명령어에 접근할 수 없습니다)
- 비기술적 사용자를 위해 지시를 명확히 하고 지나치게 기술적인 용어를 피하세요
- 대상 독자가 이미 알고 있어야 할 배경 정보는 추가하지 마세요
구조와 스타일
문서 스타일 가이드는 how-to 가이드(그리고 모든 Discourse 문서)의 구조와 스타일에 대해 알아야 할 모든 것을 다룹니다:
가이드 게시
가이드는 상위 Documentation 카테고리의 하위 카테고리에 게시하고 how-to 태그를 지정해야 합니다. 모든 가이드는 Discourse 팀의 승인이 필요하며, 이는 자동화 된 조정 프로세스를 통해 처리됩니다. 스타일 가이드는 가이드를 어디에 게시해야 하는지 결정하는 데 도움이 되도록 각 카테고리를 더 자세히 설명합니다.
가이드 유지 관리
how-to를 게시한 후에는 최신 상태를 유지하세요. 다음과 같이 유지 관리에 도움을 줄 수 있습니다:
- 답글을 주시하세요 — 커뮤니티 피드백을 가이드에 반영하세요.
- 가이드를 직접 테스트하세요 — 가이드가 여전히 정확한지 확인하기 위해 주기적으로 가이드를 따라 해보세요.
- 누락되거나 잘못된 정보를 수정하세요 — 신뢰 수준(Trust Level) 2 이상이라면 how-to의 첫 번째 게시물을 수정할 수 있습니다.
- 도움이 필요한 주기를 플래그 지정하세요 — 수정이 불가능한 경우, 게시물을 "기타(Something Else)"로 플래그 지정하고 필요한 사항을 설명하세요.
대부분의 경우, 공식 how-to 가이드는 초점을 가이드 자체에 맞추기 위해 한 달 후 댓글이 삭제됩니다.
Discourse 커뮤니티 문서 개선에 감사드립니다! 막히면 주저하지 말고 도움을 요청하세요. 시작하는 가장 좋은 방법은 기여하면서 배우는 것입니다.