diff options
| author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:17 -0500 |
|---|---|---|
| committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:42:17 -0500 |
| commit | da78a9e329e272dedb2400b79a3bdeebff387d47 (patch) | |
| tree | e6ef8aa7c43556f55ddfe031a01cf0a8fa271bfe /files/ko/mdn | |
| parent | 1109132f09d75da9a28b649c7677bb6ce07c40c0 (diff) | |
| download | translated-content-da78a9e329e272dedb2400b79a3bdeebff387d47.tar.gz translated-content-da78a9e329e272dedb2400b79a3bdeebff387d47.tar.bz2 translated-content-da78a9e329e272dedb2400b79a3bdeebff387d47.zip | |
initial commit
Diffstat (limited to 'files/ko/mdn')
45 files changed, 5007 insertions, 0 deletions
diff --git a/files/ko/mdn/about/index.html b/files/ko/mdn/about/index.html new file mode 100644 index 0000000000..79923381d6 --- /dev/null +++ b/files/ko/mdn/about/index.html @@ -0,0 +1,118 @@ +--- +title: MDN 이란 +slug: MDN/About +tags: + - Collaborating + - Community + - Copyright + - Documentation + - Guide + - Licenses + - MDN Meta +translation_of: MDN/About +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>MDN Web Docs는 웹 기술과 웹을 더 강력하게 만들어주는 소프트웨어를 배우기 위해 끊임없이 발전하는 학습 플랫폼입니다. 아래와 같은 주제를 다루고 있어요.</p> + +<ul> + <li><a href="/ko/docs/CSS" title="/en-US/docs/CSS">CSS</a>, <a href="/ko/docs/HTML" title="/en-US/docs/HTML">HTML</a>, <a href="/ko/docs/JavaScript" title="/en-US/docs/JavaScript">JavaScript</a>와 같은 웹 표준</li> + <li><a href="/ko/docs/Apps" title="/en-US/docs/Apps">열린 Web을 위한 애플리케이션 개발</a></li> + <li><a href="/ko/docs/Add-ons" title="/en-US/docs/Add-ons">Firefox 부가 기능 개발</a></li> +</ul> + +<h2 id="우리의_목표">우리의 목표</h2> + +<p>MDN의 목표는 간단합니다.<a href="/ko/docs/Web"> 열린 웹</a>의 모든 것을 완벽하고, 정확하면서도 피가 되고 살이 되는 문서를 제공해 드리는 것입니다. Mozilla에서 개발한 소프트웨어가 지원하냐 마느냐에 상관 없이, 웹에서 볼 수 있는 열린 기술이라면 문서로 만들어 보고 싶습니다.</p> + +<p>덧붙여서, 우리는 <a href="/ko/docs/Mozilla">Mozilla 프로젝트를 빌드하거나 도와주는</a> 방법과 <a href="/ko/Firefox_OS">Firefox OS</a>, <a href="/ko/Apps">Web 애플리케이션 개발</a>에 관한 문서도 제공해드리고 있습니다.</p> + +<p>MDN이 여러분이 생각하는 특정 주제를 다룰지 안 다룰지 잘 모르겠다고요? <a href="/ko/docs/MDN/Contribute/Does_this_belong">이건 MDN에 있나요?</a>을 읽어보세요.</p> + +<h2 id="도움을_주시려면">도움을 주시려면</h2> + +<p>코드를 잘 짜거나 글을 잘 쓰는 사람만 MDN을 도와줄 수 있는 것은 아닙니다! 게시물이 이해가 잘 되는지 검토하는 것부터 글을 조금 더 보태주거나, 예제 코드를 만드는 방법까지 여러분들이 MDN을 도와주는 방법은 굉장히 많답니다. 사실은 우리는 <a href="/ko/docs/MDN/Getting_started">도와줄 작업을 고르는 데 도움을 주는 글</a>이 있을 정도로 도와줄 수 있는 방법이 많답니다. 얼마나 시간을 쓸 수 있는지, 또 어느 분야에 관심이 있는지에 따라 입맛대로 고를 수 있다고요!</p> + +<p>여러분의 블로그나 홈페이지에서 <a href="/ko/docs/MDN/About/Promote">MDN을 홍보</a>해줄 수도 있구요. </p> + +<h2 id="MDN_커뮤니티">MDN 커뮤니티</h2> + +<p>MDN은 세계적인 공통체입니다. 이미 전세계 수많은 언어권에 있는 엄청난 공헌자들과 함께하고 있습니다. 우리 공동체를 더 알고 싶거나, MDN에 기여하고 싶다면 <a href="https://discourse.mozilla-community.org/c/mdn">토론방</a>과 <a href="irc://irc.mozilla.org#mdn">IRC 채널</a>을 언제든 찾아오세요. 아니면 <a href="http://twitter.com/MozDevNet">@MozDevNet</a> 트위터 계정통해서 우리가 뭘하는지 지켜보거나, 오류 신고 혹은 글쓴이, 공헌자에게 피드백(감사의 표현이면 좋겠네요!) 트윗을 날려도 됩니다.</p> + +<h2 id="MDN_Web_Docs_콘텐츠_사용법">MDN Web Docs 콘텐츠 사용법</h2> + +<p>MDN에 있는 콘텐츠는 변경이 가능하지만, 오픈소스 라이센스 아래 있습니다. </p> + +<h3 id="저작권과_라이센스">저작권과 라이센스</h3> + +<p>MDN의 콘텐츠 사용은 여러 종류의 오픈소스 라이센스들 하에서만 가능합니다. 이 장에서는 우리가 제공하는 컨텐츠 유형과 그에 따른 라이센스에 대해 설명합니다. </p> + +<h4 id="위키_문서와_기고문">위키 문서와 기고문</h4> + +<p>MDN의 위키 문서들은 Mozilla 재단 안팍의 수많은 공헌자들의 도움으로 만들어졌습니다. 별다른 표시가 없는 한 이곳에 있는 내용은 <a class="external text" href="http://creativecommons.org/licenses/by-sa/2.5/" rel="nofollow" title="http://creativecommons.org/licenses/by-sa/2.5/">크리에이티브 커먼즈 저작자 표시-동일조건 변경 허락</a>(CC-BY-SA) v2.5나 그 이후 버전의 적용을 받습니다. "Mozilla 공헌자들(Mozilla Contributors)"이라고 출처를 표기하고, 출처가 되는 위키 페이지의 (온라인) 링크를 달거나 (인쇄물) URL을 표기하여 주십시오. 가령, 이 글의 출처를 표기해야 할 때, 아래와 같이 쓸 수 있습니다.</p> + +<blockquote><a href="/ko/docs/MDN/About$history">Mozilla 공헌자들(Mozilla Contributors)</a>이 작성한 <a href="/ko/docs/MDN/About">MDN 소개</a>는 <a href="http://creativecommons.org/licenses/by-sa/2.5/">CC-BY-SA 2.5</a> 라이선스의 적용을 받습니다.</blockquote> + +<p>예시에서 보시다시피, "Mozilla 공헌자들(Mozilla Contributors)"은 인용한 페이지의 변경 기록을 링크하고 있습니다. 더 많은 설명이 필요하다면 <a href="http://wiki.creativecommons.org/Marking/Users">출처를 표시하는 가장 좋은 습관</a>을 읽어보세요.</p> + +<div class="note"> +<p><strong>참고해보세요:</strong> <a href="/en-US/docs/MDN_content_on_WebPlatform.org" title="/en-US/docs/MDN_content_on_WebPlatform.org">WebPlatform.org의 MDN 컨텐츠</a>를 참고하여 저 사이트에서 MDN의 컨텐츠를 어떻게 재사용하고 출처를 표기하는지 알아보세요.</p> +</div> + +<h4 id="예제_코드와_코드_조각">예제 코드와 코드 조각</h4> + +<p>2010년 8월 20일 이후 추가된 코드 예제는 <a class="external" href="http://creativecommons.org/publicdomain/zero/1.0/" title="http://wiki.creativecommons.org/Public_domain">저작권을 갖지 않습니다(퍼블릭 도메인 CC0)</a>. 어떠한 라이선스 공지도 필요하지 않지만, 혹시 필요하다면 다음 내용을 추가할 수 있습니다. "모든 저작권을 퍼블릭 도메인으로 모두에게 공개합니다. "Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/"</p> + +<p>2010년 8월 20일 이전에 이 위키에 작성된 코드 예제는 <a class="external" href="http://www.opensource.org/licenses/mit-license.php" title="http://www.opensource.org/licenses/mit-license.php">MIT 라이선스</a>의 적용을 받으니, 반드시 다음의 MIT 템플릿에 해당하는 권한 정보를 삽입하여야 합니다. "© <마지막으로 위키 페이지를 수정한 날짜> <위키에 이 내용을 넣은 사람의 이름>"</p> + +<h4 id="기여할_때">기여할 때</h4> + +<p>이 위키에 기여하고 싶으시다면, 반드시 크리에이티브 커먼즈 저작자 표시-동일조건 변경 허락 라이선스(또는 편집하고 있는 문서에 이미 적용된 다른 라이선스) 하에 사용할 수 있도록 문서를 작성하여야 하고, 여러분의 코드 예제는 <a href="http://creativecommons.org/publicdomain/zero/1.0/" title="http://creativecommons.org/publicdomain/zero/1.0/">Creative Commons CC-0</a>(퍼블릭 도메인) 하에 이용할 수 있어야 합니다. 이 위키에 추가함으로써 여러분들의 기여가 그러한 라이선스 아래에 이용 가능하다는 것을 이미 동의했다고 간주합니다.</p> + +<p>몇몇 오래된 컨텐츠는 위에서 설명했던 것과 다른 라이선스 하에 이용 가능합니다. 이러한 경우 해당 문서는 <a class="internal" href="/Project:en/Examples/Alternate_License_Block" title="Project:En/Examples/Alternate License Block">다른 라이선스 블럭</a>을 페이지의 맨 아래에 위치시켜 표시하고 있습니다.</p> + +<div class="warning"> +<p><strong>중요합니다:</strong> 다른 라이센스의 적용을 받는 페이지는 더이상 만들 수 없습니다.</p> +</div> + +<p><strong>작성자가 다른 이에게 부여하지 않는 한, 기여된 자료의 저작권은 해당 작성자에게 있습니다.</strong></p> + +<p>지금까지 이야기했던 내용에 대해 질문이 있거나 걱정되는 부분이 있다면 <a class="external" href="mailto:mdn-admins@mozilla.org?subject=MDN%20license%20question" rel="nofollow" title="mailto:eshepherd@mozilla.com">MDN 관리자 이메일</a> 로 연락주세요.</p> + +<h4 id="로고_상표_마크">로고, 상표, 마크</h4> + +<p>이 웹사이트의 외관과 느낌, 상표, 로고 등의 마크에 대한 저작권은 Mozilla 재단에 있습니다. 이는 크리에이티브 커먼즈 라이선스 하에 있지 않으며, 로고 및 그래픽 디자인과 같은 저작물의 범위 내에 있을 경우 이 라이선스 정책 아래에서 사용할 수 없습니다. 문서의 원문을 사용하면서 이러한 저작물의 권리도 사용하고 싶다거나, 이러한 라이선스 정책을 따르는 것에 관하여 다른 질문이 있다면, Mozilla 재단에 연락을 해야 합니다: <a class="external text" href="mailto:licensing@mozilla.org" rel="nofollow" title="mailto:licensing@mozilla.org">licensing@mozilla.org</a>.</p> + +<h3 id="MDN_링크걸기">MDN 링크걸기</h3> + +<p><a href="/ko/docs/MDN/About/Linking_to_MDN">MDN 링크하기</a>를 보고 모범사례를 확인하세요. </p> + +<h2 id="내용_다운받기">내용 다운받기</h2> + +<p><a href="https://mdn-downloads.s3-us-west-2.amazonaws.com/developer.mozilla.org.tar.gz">MDN 전체를 압축한 tar 파일</a>을 다운받을 수 있습니다. (2017년 2월 기준 2.1GB)</p> + +<h3 id="단일_페이지">단일 페이지</h3> + +<p>URL에 당신이 원하는 문서 형태의 <a href="/ko/docs/MDN/Contribute/Tools/Document_parameters#URL_parameters">문서 파라미터</a>를 추가하면 됩니다. </p> + +<h3 id="제3자_도구">제3자 도구</h3> + +<p><a href="http://kapeli.com/dash">Dash</a>(OS X용)나 <a href="http://zealdocs.org/">Zeal</a>(리눅스/윈도우용)와 같은 도구를 사용하면서 MDN의 컨텐츠를 볼 수 있습니다.</p> + +<p>또한 <a href="https://kapeli.com/">Kapeli</a>는 HTML, CSS, JavaScript, SVG, and XSLT을 포함한 <a href="https://kapeli.com/mdn_offline">오프라인 MDN 문서</a>를 출판합니다.</p> + +<h2 id="MDN의_문제점_보고하기">MDN의 문제점 보고하기</h2> + +<p><a href="/ko/docs/MDN/Contribute/Howto/Report_a_problem">MDN에 문제 보고하기</a>를 참조해 주세요.</p> + +<h2 id="MDN_Web_Docs가_지나온_길">MDN Web Docs가 지나온 길</h2> + +<p>MDN Web Docs는 (Mozilla Developer Network(MDN), Mozilla Developer Center(MDC)나 <em>Devmo</em>로 알려져 있던) Mozilla Developer Network 프로젝트는 <a class="external" href="https://www.mozilla.org/en-US/foundation/">Mozilla 재단</a>이 AOL로부터 <a href="/en-US/docs/Archive/Meta_docs/DevEdge" title="Project:en/DevEdge">DevEdge</a>의 원문 컨텐츠를 사용하는 라이선스를 취득한 2005년 초에 시작되었습니다. DevEdge 컨텐츠는 그때 자원봉사자들이 이 위키에 이전하여 개선하고 유지하기가 더욱 쉬워져, 지속적으로 유용한 내용을 만들기 위해 다듬어졌습니다.</p> + +<p><a href="/ko/docs/MDN_at_ten">10주년 기념 축하</a> 페이지에서 더 자세한 내용을 볼수 있습니다. 참여했던 사람들의 생생한 증언들도 포함되어있습니다. </p> + +<h2 id="Mozilla는">Mozilla는</h2> + +<p>우리가 누구인지에 대해서 더 알아보고 싶거나, Mozilla의 구성원이 되는 법, 아니면 그냥 우리가 어디있는지 찾아보고 싶다면 제대로 찾아오신 게 맞습니다. 우리가 무엇을 위해 나아가고, 무엇이 우리를 다르게 만드는지 궁금하시다면 <a href="https://www.mozilla.org/ko/mission/">사명</a> 페이지를 방문해보세요.</p> diff --git a/files/ko/mdn/about/mdn_services/index.html b/files/ko/mdn/about/mdn_services/index.html new file mode 100644 index 0000000000..1d04e3d468 --- /dev/null +++ b/files/ko/mdn/about/mdn_services/index.html @@ -0,0 +1,15 @@ +--- +title: MDN Services +slug: MDN/About/MDN_services +tags: + - Landing + - MDN Meta +translation_of: MDN/About/MDN_services +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN 서비스는 기존 워크플로우에 적합하고 개발자가 웹 코드를 개선할 수 있도록 설계된 웹 개개발자를 위한 실험적 유틸리티입니다. 모든 MDN 서비스는 개발 초기 알파 단계에 있으므로, 아직 코드 품질 보장에 의존하지 않는 것이 좋습니다. 만약 프로토타입으로 실험하고 싶다면, 아래의 서비스들은 실험할 준비가 되어있으며, 우리는 그것에 대해 당신의 피드백을 받고 싶습니다.</p> + +<h2 id="웹_호환성_서비스_Discord">웹 호환성 서비스 ("Discord")</h2> + +<p><a href="http://mdn-discord.herokuapp.com/">Discord</a>는 당신의 코드에서 호환성 문제를 포착하기 위한 <a href="https://help.github.com/articles/about-webhooks/">GitHub webhook</a> 입니다. 현재 CSS 코드를 <a href="https://github.com/anandthakker/doiuse.com">doiuse</a>로 스캔하고 GitHub의 코드 커밋에 주석을 추가합니다.</p> diff --git a/files/ko/mdn/community/conversations/index.html b/files/ko/mdn/community/conversations/index.html new file mode 100644 index 0000000000..9d41e6c30c --- /dev/null +++ b/files/ko/mdn/community/conversations/index.html @@ -0,0 +1,63 @@ +--- +title: MDN community conversations +slug: MDN/Community/Conversations +tags: + - Community + - Guide + - MDN Meta +translation_of: MDN/Community/Conversations +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN "활동"은 MDN 웹사이트에서 발생하지만, "커뮤니티"는 별도의 온라인 토론과 채팅으로 발생합니다.</p> + +<h2 id="비동기적_토론">비동기적 토론</h2> + +<p><span id="result_box" lang="ko"><span>정보를 공유하고 토론을 계속하기 위해, MDN은 <a href="https://discourse.mozilla-community.org/c/mdn">Mozilla Discourse 포럼에 자체 카테고리("MDN")를 가지고 있습니다</a>.</span> 문서 생성-번역-유지관리, MDN 플랫폼 개발, 미래계획, 목표설정, 진행상황 추적 등 MDN과 관련된 모든 글을 MDN 카테고리로 작성할 수 있습니다.</span></p> + +<ul> + <li><span id="result_box" lang="ko"><span>Mozilla Discourse에 가입하려면 <a href="https://discourse.mozilla-community.org/t/signing-up-and-logging-in/16017">가입 및 로그인</a> 주제를 참고하세요.</span> <span>Mozilla LDAP 계정을 가지고 있으면 이메일로 로그인할 수 있습니다.</span></span></li> + <li><span class="short_text" id="result_box" lang="ko"><span>MDN 카테고리를 구독하려면 <a href="https://discourse.mozilla-community.org/t/subscribing-to-categories-and-topics/16024">카테고리 및 주제 구독</a>을 참고하세요.</span></span></li> + <li><span id="result_box" lang="ko"><span>(선택 사항) 주로 이메일을 통해 Discourse를 사용하는 쪽을 선호하신다면 <a href="https://discourse.mozilla-community.org/t/mailman-mode/15279">메일링 리스트 환경 설정</a>을 참고하세요. </span><span>새로운 주제를 시작하려면 <a href="mailto://mdn@mozilla-community.org">mdn@mozilla-community.org</a>로 메일을 보내면 됩니다.</span> 이메일 환경 설정을 마친 경우 메일에 회신함으로써 답글을 달 수 있습니다<span>.</span> <span>회신 메일에서 의견의 문단을 나누려면, Discourse가 올바르게 분석할 수 있도록 </span></span><span lang="ko"><span>앞과 뒤에 새 줄을 2번 추가해주세요,</span></span></li> +</ul> + +<h3 id="보존용_기록"><span class="short_text" id="result_box" lang="ko"><span>보존용 기록</span></span></h3> + +<p><span id="result_box" lang="ko"><span>2017년 6월 이전에는 MDN 관련 토론이 Google 그룹과 함께 게이트웨이되고 보관 된 메일 링리스트에서 진행되었습니다.</span> <span>이전 토론을 검색하려면 이전 메일 링리스트에 해당하는 Google 그룹을 살펴보십시오.</span> <span>(예, 우리는이 이름들이 겹쳐지고 혼동을 일으킨다는 것을 알고 있습니다. 역사적인 사고입니다. 죄송합니다.)</span></span></p> + +<dl> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdc">mozilla.dev.mdc</a> a.k.a dev-mdc</dt> + <dd><span class="short_text" id="result_box" lang="ko"><span>이 목록은 MDN의 문서 내용에 대한 토론 용이었습니다.</span></span></dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdn">mozilla.dev.mdn</a> a.k.a dev-mdn</dt> + <dd><span class="short_text" id="result_box" lang="ko"><span>이 목록은 MDN의 기본 Kuma 플랫폼 개발 작업에 관한 것입니다.</span></span></dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.mdn">mozilla.mdn</a> a.k.a mdn@</dt> + <dd><span id="result_box" lang="ko"><span>이 포럼은 MDN 웹 사이트 및 기타 관련 이니셔티브를위한 높은 수준의 계획 및 우선 순위 토론을위한 것입니다.</span></span></dd> +</dl> + +<h2 id="IRC_채팅하기">IRC 채팅하기</h2> + +<p>IRC(Internet Relay Chat)는 커뮤니티 멤버들끼리 매일 채팅하고 실시간으로 토론하기 위한 방법으로 선호됩니다. 저희는 MDN에 관련된 토론을 위해 irc.mozilla.org 서버에 있는 몇 가지 채널을 사용합니다.</p> + +<dl> + <dt><a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/mdn">#mdn</a></dt> + <dd>이 채널은 MDN 콘텐츠에 대해 토론하기 위한 기본적인 채널입니다. 저희는 작성, 콘텐츠 구성 등등에 대해 얘기합니다. 또한 저희는 여기서 "water cooler" 대화를 가집니다. 이는 저희의 커뮤니티가 연락을 유지하고 어울리기 위한 방법입니다. 또한 이는 데모 스튜디오, 프로필 등과 같이 MDN의 다른 측면(플래폼 개발이 아닌 부분)에 대해 토론하는 곳입니다.</dd> + <dt> </dt> + <dt><a href="irc://irc.mozilla.org/mdndev" title="irc://irc.mozilla.org/mdndev">#mdndev</a></dt> + <dd><font color="#4D4E53" face="Open Sans, Arial, sans-serif">이 채널은 우리의 개발 팀 - MDN이 작동하도록 코드를 작성하는 사람들 - 이 어울리고 그들의 일과를 토론하기 위한 곳입니다. 당신이 이 채널에 합류하고 개발에 참여하거나 혹은 단순히 당신이 소프트웨어에 대한 이슈에 관해 질문을 하는 것을 환영합니다.</font></dd> +</dl> + +<p>이 채널들은 대부분 북미 지역에서 주중에 활발합니다.</p> + +<p>당신은 IRC에 대해서 좀 더 <a href="http://wiki.mozilla.org/IRC">알고 싶어하고</a>, <a href="https://addons.mozilla.org/en-US/firefox/addon/chatzilla/">ChatZilla</a>와 같은 설치형 IRC 클라이언트를 사용하고 싶어 할 것입니다. 이는 쉽고 빠르게 설치하고 사용할 수 있는 Firefox add-on에서 실행될 수 있습니다. 만약 IRC에 익숙하지 않다면, 참여하기 쉬운 방법에는 미리 <a href="http://scrollback.io/mozdn/">mdn</a>과 <a href="http://scrollback.io/mdndev/">mdndev </a>채널들에 맞추어 설계된 <a href="https://chat.mibbit.com/">mibit</a>과 같은 웹기반 IRC 클라이언트를 사용하는 것이 있습니다. </p> + +<h2 id="회의_및_기타_행사에_참가"><span class="short_text" id="result_box" lang="ko"><span>회의 (및 기타 행사)에 참가</span></span></h2> + +<p><span id="result_box" lang="ko"><span>MDN 팀은 MDN 커뮤니티에 열려있는 여러 정기 모임을 개최합니다.</span> <span>일정, 의제 및 메모, 참여 방법에 대한 자세한 내용은 Mozilla wiki의 <a href="https://wiki.mozilla.org/MDN/Meetings">MDN Meetings</a> 페이지를 참조하십시오.</span></span></p> + +<p><span id="result_box" lang="ko"><span>이 회의 및 기타 회의, 지역 회의 및 기타 행사에 대한 <a href="https://www.google.com/calendar/embed?src=mozilla.com_2d35383434313235392d323530%40resource.calendar.google.com">MDN 이벤트</a> 달력을보십시오.</span> <span>되풀이 모임은 <a href="https://wiki.mozilla.org/MDN/Meetings">MDN Meetings wiki</a> 페이지에 요약되어 있습니다.</span></span></p> + +<p> </p> + +<p>If you see a meeting which takes place in the "mdn" channel on our Vidyo videoconferencing system, you can <a href="https://v.mozilla.com/flex.html?roomdirect.html&key=gMM1xZxpQgqiQFNkUR3eBuHgxg">join the conversation on the web</a>.</p> + +<p> </p> diff --git a/files/ko/mdn/community/index.html b/files/ko/mdn/community/index.html new file mode 100644 index 0000000000..faff8c5f2e --- /dev/null +++ b/files/ko/mdn/community/index.html @@ -0,0 +1,46 @@ +--- +title: MDN 커뮤니티 참여하기 +slug: MDN/Community +tags: + - Community + - Guide + - Landing + - MDN Meta +translation_of: MDN/Community +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<div class="summary"> +<p>MDN 웹 문서는 위키 그 이상입니다. MDN은 공개 웹 기술을 사용하는 개발자들을 위해 뛰어난 자료를 만드는 사람들이 함께 작업하는 커뮤니티입니다.</p> +</div> + +<p>당신이 MDN에 기여하시는 것도 물론 좋지만, 더 나아가 공식 커뮤니티에 참여하시면 정말 기쁘겠습니다. 참여하시는 방법은 다음 세 단계면 됩니다. </p> + +<ol> + <li><a href="/ko/docs/MDN/Contribute/Howto/Create_an_MDN_account">먼저 MDN 계정 생성을 만들고</a></li> + <li><a href="/ko/docs/MDN/Community/Conversations">토론에 참여하고</a></li> + <li><a href="/ko/docs/MDN/Community/Whats_happening">어떤 일이 일어나는지 지켜보세요.</a></li> +</ol> + +<h2 id="커뮤니티가_돌아가는_방법">커뮤니티가 돌아가는 방법</h2> + +<p>MDN 커뮤니티를 더 자세히 설명하는 글입니다.</p> + +<div class="twocolumns"> +<dl> + <dt><a href="/ko/docs/MDN/Community/Roles">커뮤니티의 역할</a></dt> + <dd>MDN 커뮤니티에는 특정 책임이 주어진 몇가지 역할들이 있습니다. </dd> + <dt><a href="/ko/docs/MDN/Community/Doc_sprints">문서화 스프린트</a></dt> + <dd>문서화 스프린트 운영 가이드입니다. 스프린트를 운영해온 사람들의 유익한 조언과 팁이 포함되어있습니다. </dd> + <dt><a href="/ko/docs/MDN/Community/Whats_happening">어떤일이 일어나는지 지켜보기 </a></dt> + <dd>MDN은 <a href="https://wiki.mozilla.org/MDN">Mozilla Developer Network community</a>가 제공합니다. 하고있는 일에 대한 정보를 공유하는 몇가지 방법을 소개합니다. </dd> + <dt><a href="/ko/docs/MDN/Community/Conversations">MDN 커뮤니티의 토론</a></dt> + <dd>MDN의 "작업"은 MDN 사이트에서 하지만, "소통"은 (비동기) 토론과 (실시간) 온라인 채팅을 통해 일어납니다.</dd> + <dt><a href="/ko/docs/MDN/Community/Working_in_community">커뮤니티에서 작업하기</a></dt> + <dd>규모와 관계 없이 MDN 문서 기여시 반드시 알아야 할 것은 MDN 커뮤니티의 일원으로 어떻게 일할는지를 아는 것입니다. 이 글은 다른 글쓴이, 기술팀과 상호작용을 어떻게 잘 할 수 있는지를 알려줍니다. </dd> + <dt></dt> + <dt></dt> +</dl> +</div> diff --git a/files/ko/mdn/community/roles/admins/index.html b/files/ko/mdn/community/roles/admins/index.html new file mode 100644 index 0000000000..3fb6fed5bf --- /dev/null +++ b/files/ko/mdn/community/roles/admins/index.html @@ -0,0 +1,59 @@ +--- +title: MDN administrator role +slug: MDN/Community/Roles/Admins +translation_of: MDN/Community/Roles/Admins +--- +<div>{{MDNSidebar}}</div><p>MDN의 규칙 중에서, 관리자의 규칙은 최고의 권한을 가지고 있습니다. 관리자들은 사이트의 플래폼의 모든 기능들과, 심지어 화면 뒷쪽의 자료구조에 제한된 접근을 할 수도 있습니다. 이 페이지는 관리자들이 할 수 있는 일들과, 어떻게 당신이 그러한 것들을 돕기위하여 관리자에게 연락할 수 있는지를 서술합니다.</p> + +<h2 id="현재_MDN_관리자들">현재 MDN 관리자들</h2> + +<p>현재, 다음에 오는 유저들은 관리자들입니다. {{UserLink("Sheppy")}}, {{UserLink("fscholz")}}, {{UserLink("teoli")}}, {{UserLink("jswisher")}}</p> + +<h2 id="관리자_권한">관리자 권한</h2> + +<p>관리자들은 많은 양의 특수한 능력을 가지고 있습니다. 다음은 그 중에서 몇가지입니다:</p> + +<h3 id="페이지_이동">페이지 이동</h3> + +<p>모든 관리자들은 페이지 혹은 페이지 묶음을 이동할 권한이 있습니다. </p> + +<h3 id="페이지_삭제">페이지 삭제</h3> + +<p>모든 관리자들은 MDN 위키의 어떤 페이지를 삭제할 권한이 있습니다. 하지만, 보통, 당신이 페어떤 페이지가 삭제되길 원한다면, 간단히 "junk"태그를 페이지에 추가하세요. 내용을 수정하거나 삭제하지 마세요(그렇게 하는 것은 페이지가 실제로 삭제될 필요가 있는지 확실히 확인하기 힘들어집니다.) 만약 특수한 문제가 있다면 (예를 들어 공격적인 내용), 관리자에 직접 연락해주세요.</p> + +<p>관리자들은 또한 이전에 삭제된 페이지들을 복구할 권한이 있습니다.(최소한, 그 페이지들이 시스템으로부터 삭제되지 않았을때까지). 만약 당신이 어떤 페이지가 부적절하게 삭제되었다는 것을 발견하면, 관리자에게 연락하세요.</p> + +<h3 id="권한을_부여하거나_삭제">권한을 부여하거나 삭제</h3> + +<p>관리자들은 유저의 권한을 변경할 수 있습니다. 이러한 과정 뒤에, 어떤 처리가 있습니다; 더 많은 정보를 위하여, <a href="/en-US/docs/MDN/Contribute/Tools_with_restricted_access">도구</a>들을 보세요.</p> + +<h3 id="사용자들을_금지하거나_풀어주기">사용자들을 금지하거나 풀어주기</h3> + +<p>때때로, 사용자들은 그들이 MDN 컨텐츠를 수정하지 못하도록 금지할 필요가 있을 만한 문제를 일으킵니다. (임시적으로 혹은 영구적으로). 관리자들은 (토픽 드라이버들 혹은 지역화 팀 리더들 또한)은 관리자들을 이미 존재하는 금지를 풀어줄뿐만 아니라, 사용자들을 금지할 권한이 있습니다.</p> + +<h3 id="zones을_생성편집">zones을 생성/편집</h3> + +<p>MDN 관리자들은 새로운 zones을 생성하고, 존재하는 페이지를 zones에 넣고, zone의 정보와 CSS를 수정할 수 있습니다. zones에 대해 더 많은 정보를 원하면, <a href="/en-US/docs/MDN/User_guide/Zone_administration">Zone 관리자</a> 가이드를 보세요. </p> + +<h3 id="유저_정보_편집">유저 정보 편집</h3> + +<p>MDN 관리자들은 아직 편집을 위한 유저 인터페이스가 존재하지 않는 유저 정보를 변경할 권한이 있습니다. 만약 당신의 이름을 변경하거나, email 주소를 예전의 MDN 계정과 연동시킬 필요가 있다면, <strong>우리는 당신을 도와줄 수 있다고 약속할 수 없습니다; 모든 요청이 만족될수는 없습니다.</strong></p> + +<h3 id="캘린더_항목을_추가하거나_변경">캘린더 항목을 추가하거나 변경</h3> + +<p>MDN 관리자들은 <a href="https://mail.mozilla.com/home/publiccalendar@mozilla.com/MDN_Events.html">MDN 이벤트 캘린더</a>에 추가하거나 업데이트를 할 수 있습니다. 만약 당신의 팀이 미팅을 가지거나, 이미 존재하는 이벤트에 문제가 보인다면, 부디 관리자들이 알 수 있게 해주세요, 우리가 처리하겠습니다.</p> + +<h3 id="KumaScript_macros를_편집">KumaScript macros를 편집</h3> + +<p>모든 MDN 관리자들은 <a href="/en-US/docs/MDN/Kuma/Introduction_to_KumaScript">KumaScript macros</a>를 편집할 수 있습니다.(또한 KumaScript 템플릿으로도 알려져 있습니다. 비록 그 팀이 정황상 비난 받더라도).</p> + +<h2 id="관리자에게_연락하기">관리자에게 연락하기</h2> + +<p>당신은 특정한 관리자를 위에 있는 그들의 프로필을 이용하거나, 혹은 <a href="mailto:mdn-admins@mozilla.org?subject=Admin%20help%20request">mdn-admins@mozilla.org</a>에 메시지를 전송함으로써 연락할 수 있습니다. </p> + +<h2 id="다음도_같이_보세요">다음도 같이 보세요</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute/Drivers_and_curators">Topic drivers and curators</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Localization_driver_role">Localization driver role</a></li> +</ul> diff --git a/files/ko/mdn/community/roles/index.html b/files/ko/mdn/community/roles/index.html new file mode 100644 index 0000000000..c98b89f4e1 --- /dev/null +++ b/files/ko/mdn/community/roles/index.html @@ -0,0 +1,14 @@ +--- +title: 커뮤니티 역할 +slug: MDN/Community/Roles +tags: + - Community + - Landing + - MDN Meta +translation_of: MDN/Community/Roles +--- +<div>{{MDNSidebar}}</div> + +<p>MDN 커뮤니티에는 각자 맡은 책임이 있는 역할이 몇 가지 있습니다.</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ko/mdn/community/roles/localization_driver_role/index.html b/files/ko/mdn/community/roles/localization_driver_role/index.html new file mode 100644 index 0000000000..f3bde14ee8 --- /dev/null +++ b/files/ko/mdn/community/roles/localization_driver_role/index.html @@ -0,0 +1,66 @@ +--- +title: 지역화 운동가의 역할 +slug: MDN/Community/Roles/Localization_driver_role +translation_of: MDN/Community/Roles/Localization_driver_role +--- +<div>{{MDNSidebar}}</div><p>MDN 지역화 운동가는 특정 언어나, 지역을 위한 MDN의 문서 활동들을 조정하고 이끌고 있습니다. 그들은 MDN의 구조 문서, 번역가들의 흥미, 그리고 모질라에 관해 정보를 유지합니다. 그들은 그들의 지역에 관련된 모든 번역을 할 필요는 없습니다. 그리고 사실상, 그들은 번역에 관심있는 기여자들의 그룹을 모으고, 그룹 사이에서 작업을 조정하도록 권해집니다. 활발한 지역 목록과 현재 l10n 운동가들의 <a href="/en-US/docs/MDN/Contribute/Localize/Localization_projects">지역화 프로젝트</a> 페이지를 보십시오. </p> + +<h2 id="왜_지역화_운동가가_돼야_하는가">왜 지역화 운동가가 돼야 하는가?</h2> + +<p>l10n 운동가팀이 되는것은 커뮤니티에 깊게 빠져들게될 기회를 제공하며, 그리고 어떻게 모질라가 당신의 언어 커뮤니티에 인식되는지에 대한 강력한 영향을 가지는 것입니다. 아마도 당신의 현재 직업에 혹은 다른 직업을 얻는 것에 도움을 주기위해 이런 전문 지식을 사용할 수 있습니다.</p> + +<p>게다가, l10n 운동가로써, 당신은 웹의 품질을 향상시키기 위한 원동력이 될 수 있습니다.</p> + +<h2 id="l10n_운동가가_되는_것">l10n 운동가가 되는 것</h2> + +<p>아직 l10n 운동가를 가지지 않은 지역에서 l10n운동가가 되기위해서는, 다음의 자질을 만족할 필요가 있습니다.</p> + +<ul> + <li>지역의 언어에 대한 전문지식.</li> + <li>지역에 대한 활발한 기여(적어도 한달에 한번).</li> + <li>다양하고, 지리적으로 분산된 커뮤니티와 의사소통하는 능력</li> +</ul> + +<p>l10n 운동가가 되기 위한 최적의 방법은 그들 처럼 활동하는 것입니다. l10n 운동가들의 과제의 대부분은 특별한 능력이나 허가를 요구하지 않습니다.</p> + +<p>당신이 위의 요구사항을 만족했다면, 당신은 운동가가 되고 싶어하는 지역의 <a href="/en-US/docs/MDN/Community#Join_our_mailing_lists">dev-mdc 메일링 리스트</a>에 당신의 자질에 대한 개요와 이 지역에 대해 무엇이 필요한지에 대한 설명과 함께 글을 올릴 수 있습니다. 만약 당신이 자질들을 만족한다면, 저희는 당신이 자립하고, 어떻게 당신에게 주어진 새로운 특권을 사용하는지에 대한 기본이 훈련되도록 노력할 것입니다.</p> + +<h3 id="l10n_운동가들_도와주기"><strong>l10n 운동가들 도와주기</strong></h3> + +<p>저희는 각 지역의 운동가들의 수를 제한하지 않습니다. 당연히, 그들은 협력할 필요가 있습니다 :-) 그러니 그들을 도와주는 것을 망설이지 마세요. 스팸과 오류같은 컨텐츠를 감시하는 것을 도와주세요. 새롭게 번역된 기사를 편집하는 것과 이미 번역된 기사들을 갱신하는 것 모두 당신이 도울 수 있는 작업들입니다.</p> + +<h2 id="의무">의무</h2> + +<p>l10n 운동가들의 역할은 다수의 중요한 의무가 달려옵니다. 그 의무들중 몇 가지에는:</p> + +<ul> + <li>작업이 완료되고, 사람들이 실수로 같은 것을 두 번 번역하지 않도록 확실히 하기 위해서, 한 언어의 번역에 종사하는 커뮤니티를 조정하라. wiki뿐만 아니라 MDN웹 사이트의 UI번역을 위해 그 지역의 새로운 기여자를 선발하고 협업해라.</li> + <li>번역된 페이지를 조직화 해라. 문서의 계층도, 즉 구조상의 오류를 고쳐라. 번역가들의 커뮤니티에 가장 중요한 페이지와 커뮤니케이션 해라. 메크로 또한 번역된다는 것을 명심하라.</li> + <li><a href="/en-US/docs/MDN/Community#Join_our_biweekly_meetings_(and_other_events)">격주로 진행되는 MDN 커뮤니티 모임</a>에 참여하거나,<a href="/en-US/docs/MDN/Community#Join_our_mailing_lists"> dev-mdc 메일링 리스트</a>의 토론에 참여하는 것과 같은 방법들을 통해, 문서 작업의 진행과 상태를 MDN 커뮤니티와 공유해라.</li> + <li>당신이 무리없이 할 수 있는만큼만 작업하는데 시간을 할애하여라; 당신은 모든 작업을 할 필요가 없으나 만약 조금이라도 기여한다면 도움이 될 것이다.</li> +</ul> + +<h2 id="특권">특권</h2> + +<p>MDN의 모든 허가된 사용자들에게 주어진 특권에 더하여(변경을 되돌리기와 같은 l10n 운동가들은 이러한 특권들을 가지고 있습니다:</p> + +<ul> + <li>페이지들의 묶음 혹은 페이지들 이동시키기</li> + <li>파일 첨부 관리하고 업로드하기</li> + <li>KumaScript 메크로들을 수정하기</li> +</ul> + +<p>저희는 앞으로 기여자들의 리스트에 접근하거나, 대량으로 이메일을 보내는 사람들을 차단하는 권한과 같은 새로운 특권들을 추가할 예정입니다. </p> + +<h2 id="임무를_떠나서">임무를 떠나서</h2> + +<p>한 명의 l10n 운동가가 되면, 당신은 임무에 영원히 머무를 필요가 없습니다. 당신의 흥미, 우선순위, 그리고 할애가능한 시간은 바뀔 수 있습니다. 당신이 한 명의 l10n 운동가로써 계속 할 수 없다고 생각한다면(혹은 당신이 이미 그만두었다는 것을 깨달았다면), 부디 아래의 절차를 취해주세요:</p> + +<ul> + <li>당신이 l10n 운동가에서 물러남을 알리기 위해 MDN 문서의 지도자(혹은 다른 MDN 관리자들)인<a href="/en-US/profiles/sheppy"> Eric Shepherd</a>에게 연락해주세요</li> + <li>만약 가능하다면, 당신의 지역에서 활발한 기여자에게 l10n 운동가를 시작하도록 요청해주세요. 만약 그 사람이 동의한다면, MDN 문서 지도자에게 알려주세요.</li> +</ul> + +<p>만약 당신이 2달 이상동안, MDN(혹은 dev-mdc 메일링 리스트)에 활발히 활동해오지 않았다면, l10n 운동가를 계속하기를 원하는 지를 확인하기 위해 연락받을 수 있습니다. 3달 이상 활동하지 않거나, 연락받았을 때 응답하지 않은 L10n 운동가들은 그들의 역할로부터 삭제될 수 있습니다. </p> + +<p> </p> diff --git a/files/ko/mdn/community/working_in_community/index.html b/files/ko/mdn/community/working_in_community/index.html new file mode 100644 index 0000000000..0398e29823 --- /dev/null +++ b/files/ko/mdn/community/working_in_community/index.html @@ -0,0 +1,110 @@ +--- +title: 커뮤니티에서의 활동 +slug: MDN/Community/Working_in_community +translation_of: MDN/Community/Working_in_community +--- +<div>{{MDNSidebar}}</div> + +<p>A major part of contributing to MDN documentation on any significant scale is knowing how to work as part of the MDN community. This article offers tips to help you make the most of your interactions with both other writers and with development teams.</p> + +<h2 id="에티켓_가이드라인">에티켓 가이드라인</h2> + +<p>Mozilla 커뮤니티와 함께 일하면서 지켜주셨으면 하는 사항들입니다.</p> + +<ul> + <li>예의를 지켜주세요! 합의점을 찾기 힘든 사항이더라도 우리 모두는 더 나은 웹을 만들고자하는 공통적인 목표가 있습니다.</li> + <li>요구하기보다는 질문으로 정중하게 물어봐주세요. 요구할 때보다 정중하게 도움을 요청한다면 기대 이상의 좋은 답변을 기대하실 수 있을 것 입니다. 개발 커뮤니티 일원 모두 문서 작업이 중요하다는 사실을 인지하고 있습니다. 그러나 상대방에게 존중심이 부족한 말이나 행동은 그에 걸맞는 대우를 받을 수 있습니다. </li> + <li>정보의 필요성과 긴급성, 그리고 다른 일원분들의 시간 투자를 염두에 두고 균형을 잘 조율해주시길 바랍니다. 정말로 필요한게 아니라면, 대화에 참가하고 있는 분들에게 폐를 끼칠 정도의 많은 정보를 요청하거나 재촉하지 말아주세요.</li> + <li>당신의 요청은 다른 사람들의 소중한 시간을 사용하게 된다는 점을 염두에 두시고, 그 시간을 현명히 사용해주시길 바랍니다.</li> + <li>문화적 차이에 대해 존중심을 보여주세요. Mozilla 는 다국적, 다문화적 팀입니다. 다른 사람과 대화할 때, 상대방의 문화를 염두에 두어주시길 바랍니다.</li> + <li>진행 중인 대화에 끼어들기보다 새로운 대화를 시작해 주세요. Don't inject your questions into an unrelated conversation just because the people you need to talk to are paying attention to it. While convenient for you, this can irritate the people you're trying to talk to, and result in a less than ideal outcome.</li> + <li>{{interwiki("wikipedia", "bikeshedding")}}는 자제해 주세요. 열정이 사소한 것에 대한 집착으로 이어지지 않도록 조심해주세요. 대화가 주제에서 이탈할 수 있고 불편해질 수 있습니다.</li> +</ul> + +<h2 id="Be_tactful">Be tactful</h2> + +<p>Always be tactful and respectful when communicating with others.</p> + +<h3 id="Politely_pointing_out_mistakes">Politely pointing out mistakes</h3> + +<p>If your purpose in contacting someone is to ask them to do something differently, or to point out a mistake they've been making (especially if they repeatedly do it), start your message with a positive comment. This softens the blow, so to speak, and it demonstrates that you're trying to be helpful, rather than setting you up as the bad guy.</p> + +<p>For example, if a new contributor has been creating lots of pages without tags, and you'd like to point out this problem, your message to them might look like this (the stuff you'd need to change for each case is underlined):</p> + +<blockquote> +<p>안녕하세요 홍길동씨, <u>웜홀 API 문서</u> 에 대한 홍길동씨의 기여에 대해 감사드립니다. 저는 특히 홍길동씨께서 <u>가독성과 세부정보를 균형있게 서술한 점을 인상깊게 보았습니다.</u> 아마도 작업하시면서 <u>correct tag를 페이지마다 추가해주신다면 </u>이 문서를 더 유익하고 잘 만들어 나갈 수 있을 것 같습니다.</p> + +<p><u>자세한 사항은 MDN 태그가이드를 이용해 주세요(<a href="/ko/docs/MDN/Contribute?Howto/Tag/">https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag</a>)</u></p> + +<p>다시 한번 감사를 드리며 앞으로의 기여활동도 기대하겠습니다!</p> +</blockquote> + +<h2 id="지식_공유">지식 공유</h2> + +<p>MDN 프로젝트에 참여하면서 무슨 일들이 일어나는지 파악하고 다른 멤버들과 소통하는 것이 본인에게 도움이 됩니다. 커뮤니티 내의 다른 분들과 소통하므로 아이디어를 얻거나 공유할 수 있습니다. 우리는 누가 주체가 되어 무슨 일을 진행하는지 알 수 있는 도구들과 리소스들을 제공하고 있습니다.</p> + +<h3 id="Communication_channels">Communication channels</h3> + +<p>There are several ways you can engage with community members (either developers or writers), each of which has some of its own particular rules of etiquette.</p> + +<h4 id="Discourse">Discourse</h4> + +<p>The <a href="https://discourse.mozilla.org/c/mdn">MDN Discourse forum</a> is a good place to ask general questions about MDN contribution and start discussions.</p> + +<h4 id="Chat">Chat</h4> + +<p>Use the Matrix chat system to reach people in real time. MDN staff members are available in the <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs room</a>, and are active during work days in Europe and North America. Explore the other chat rooms to find people involved in topics you're interested in.</p> + +<h4 id="GitHub">GitHub</h4> + +<p>If you find a problem on MDN, or want to ask a question, you can file an issue over on our <a href="https://github.com/mdn/sprints/issues">GitHub sprints repo issues</a>! They will then be triaged and actioned at some point in the future.</p> + +<h4 id="Email">Email</h4> + +<p>Sometimes, a private email exchange between you and one or more other people is the way to go, if you have their email address.</p> + +<div class="note"> +<p><strong>Note:</strong> As a general rule, if someone has posted their email address on documents about the technology you're documenting, has given you their email address personally, or generally has a well-known email address, email is an acceptable "first contact" approach. If you have to dig for it, you probably should try to get permission Discourse or a mailing list first, unless you've exhausted all other attempts at getting in touch.</p> +</div> + +<h3 id="Content_status_tools">Content status tools</h3> + +<p>We have several useful tools that provide information about the status of documentation content.</p> + +<dl> + <dt><a href="/dashboards/revisions">Revision dashboard</a></dt> + <dd>The revision dashboard provides a fantastic tool to review changes made to MDN content. You can see recent history, choose a range of time to view, and filter based on things like locale, contributor's name, and topic. Once you're looking at a set of revisions, you can view the changes made in each revision, quickly open the page, see a full history, or even revert the changes (if you have those privileges).</dd> + <dt><a href="https://developer.mozilla.org/en-US/docs/MDN/Doc_status/Overview">Documentation status overview</a></dt> + <dd>Our <a href="https://developer.mozilla.org/en-US/docs/MDN/Doc_status/Overview">documentation status overview</a> page provides a list of all the areas of MDN that have been configured for status tracking, with information about how many pages therein need different types of work done. Click through to a particular topic area to see detailed lists of content that needs work, such as pages that have no tags, or are tagged with indicators that certain types of work need to be done. You can even see lists of pages that haven't been updated in a long time and may be out of date, as well as a list of bugs that have been flagged as impacting the documentation in that area.</dd> + <dt><a href="/en-US/docs/MDN/Plans">Documentation project plans</a></dt> + <dd>We have a number of writing projects that are in the planning stages, or are large and ongoing, for which we have written planning documents to help us keep track of what we need to get done.</dd> + <dt><a href="https://tree.taiga.io/project/viya-mdn-durable-team">MDN Taiga</a></dt> + <dd>The MDN staff writers use a tool called Taiga to manage current and future documentation projects. You can take a look to see what we're doing and how it's going, and you can see what projects we'd like to see happen soon. Some of those will be taken on by staff writers, but you should feel free to take one over if you like! For more information about the agile processes followed by the MDN team, see our <a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team/Processes">Process page on the Mozilla wiki</a>.</dd> +</dl> + +<h2 id="The_development_community">The development community</h2> + +<p>Possibly the most important relationships to develop and maintain, as a member of the MDN writing community, are those you develop and sustain with the developers. They create the software we're developing, but they're also the most useful source of information we have. It's crucial that we maintain good relations with developers—the more they like you, the more likely they are to answer your questions quickly, accurately, and thoroughly!</p> + +<p>In addition, you represent the MDN writing community. Please help ensure we keep our excellent working relationship with the dev team by making every interaction they have with the writing team be a good one.</p> + +<p>On a related note, a great way to find the right person to talk to is to look at the <a href="https://wiki.mozilla.org/Modules">module owners lists</a>.</p> + +<h2 id="The_writing_community">The writing community</h2> + +<p>The writing community is a large one. While the number of extremely frequent, or large-scale contributors is relatively small, there are many dozens or hundreds of people who contribute at least now and then. Fortunately, these are by and large awesome people with a genuine love of the Web, Mozilla, and/or documentation, and interacting with them is almost always pretty easy.</p> + +<p>See the article <a href="/en-US/docs/MDN/Community" title="/en-US/docs/Project:MDN/Contributing/Join_the_community">Join the community</a> for more information about the MDN community.</p> + +<p>The most frequent place you'll directly interact with other writers is in the <a href="https://discourse.mozilla.org/c/mdn">Discourse forum</a>.</p> + +<p>By keeping in mind the {{anch("General etiquette guidelines")}}, you'll find that usually, things go very smoothly.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Project:MDN/Contributing" title="/en-US/docs/Project:MDN/Contributing">Contributing to MDN</a></li> + <li><a href="/en-US/docs/Project:MDN/Contributing/Join_the_community" title="/en-US/docs/Project:MDN/Contributing/Join_the_community">MDN community</a></li> + <li><a href="http://matt.might.net/articles/how-to-email/" title="http://matt.might.net/articles/how-to-email/">How to send and reply to email</a></li> + <li><a href="http://blog.gerv.net/2012/10/how-to-be-a-mozillia/">How to be a Mozillian</a></li> +</ul> diff --git a/files/ko/mdn/contribute/creating_and_editing_pages/index.html b/files/ko/mdn/contribute/creating_and_editing_pages/index.html new file mode 100644 index 0000000000..6993674a4f --- /dev/null +++ b/files/ko/mdn/contribute/creating_and_editing_pages/index.html @@ -0,0 +1,166 @@ +--- +title: 페이지 생성 및 수정 +slug: MDN/Contribute/Creating_and_editing_pages +tags: + - 초보자 + - 페이지생성 + - 페이지수정 + - 페이지편집 +translation_of: MDN/Contribute/Howto/Create_and_edit_pages +--- +<div>{{MDNSidebar}}</div><p>신규 공헌자가 이미 있는 문서를 수정하거나 신규 문서를 생성하는 법에 대해 설명합니다. </p> + +<h2 id="기존_페이지_수정하기">기존 페이지 수정하기</h2> + +<p>페이지를 수정하기 위해서:</p> + +<ul> + <li>오른쪽 최상단 근처의 <strong>Edit</strong> 버튼을 클릭하세요.</li> + <li>페이지가 로드되며 직접 정보를 추가하거나 삭제할 수 있는 편집화면이 뜹니다. </li> + <li>문단 추가, 텍스트 삭제, 헤드라인 삽입, 그리고 문서 작성 및 편집을 위한 기본적인 기능 이상의 것을 수행할 수 있습니다.</li> +</ul> + +<p>MDN에 탑재된 편집기 사용에 대한 좀 더 세부적인 내용은 <a href="/ko/docs/MDN/Contribute/Editor">MDN 편집기 가이드</a>에 있는 <a href="/ko/docs/MDN/Contribute/Editor/Basics">편집기 UI 요소</a>를 참고하세요.</p> + +<h3 id="변경_내용_미리보기">변경 내용 미리보기</h3> + +<p>수정한 내용이 어떤 모습일지 보기 위해서는...</p> + +<ul> + <li>페이지 상단이나 하단에 있는 "미리보기" 버튼을 클릭하세요.</li> + <li>그러면 새 창이나 탭으로 수정 사항을 포함하고 있는 미리보기 페이지가 열립니다.</li> + <li>이 버튼을 클릭할 때 마다, 가장 최근에 수정한 내용으로 미리보기 페이지가 새롭게 로딩됩니다.</li> +</ul> + +<p>하지만!! 미리보기는 저장된 페이지가 아닙니다. 저장 전 편집 페이지를 닫지 않도록 <strong>주의하세요!!</strong></p> + +<h3 id="리비전_답글">리비전 답글</h3> + +<p> 미리보기로 확인했다면, 변경사항(리비전)를 저장하고 싶을 겁니다. 저장 전, 편집영역 아래 있는 리비전 답글 영역에 변경 사유를 남겨주세요. 다른 공헌자들이 참고할 수 있도록요. 예를 들면, 새로운 섹션을 추가했거나, 좀 더 정확한 용어를 쓰기 위해 단어를 수정했거나, 언어를 구분하기 위해 문장을 다시 썼거나, 중복되는 내용이기 때문에 정보를 제거했다 등을 적으면 됩니다. </p> + +<h3 id="목차">목차</h3> + +<p>페이지 상단에 "이동"이라는 목차 영역은 페이지에 있는 소제목 이동 링크를 자동으로 만들어준 것입니다. 소제목을 바꾸면 목차명도 바뀝니다. 편집화면 '설명 번역'의 "TOC" 드롭다운 메뉴를 통해서 목차를 제거하거나 목차 깊이를 조절할 수 있습니다. </p> + +<h3 id="태그">태그</h3> + +<p>페이지 내용과 기능을 설명하는 태그를 페이지의 편집 섹션 아래에서 추가하거나 제거할 수 있습니다. 어떤 태그를 적용할 것인지에 대해 자세히 알고 싶으면 <a href="/en-US/docs/MDN/Contribute/Tagging">페이지에 알맞은 태그를 붙이는 방법</a>을 보세요.</p> + +<h3 id="검토가_필요한가요">검토가 필요한가요?</h3> + +<p>전문가 또는 숙련된 공헌자의 검토가 필요하다고 생각되면, 저장하기 전에, 검토 요청 체크박스를 이용하여, (코드 샘플, API 혹은 테크놀로지에 대한) 기술상의 검토, (산문, 문법 및 내용에 대한) 편집상의 검토, (KumaScript 코드에 대한) 템플릿 검토를 요청할 수 있습니다.</p> + +<h3 id="자료_첨부">자료 첨부</h3> + +<p>자세한 설명을 추가하기 위해 자료를 첨부하고 싶다면, 페이지 하단에서 첨부할 수 있습니다. </p> + +<h3 id="개시_버리기_또는_개시하고_계속_편집">개시, 버리기 또는 개시하고 계속 편집</h3> + +<p>편집을 완료하고, 미리보기 한 결과에도 만족했다면, 페이지 제목의 오른쪽이나 페이지 하단에 있는 녹색의 "변경 사항 저장"을 클릭하여 작업한 결과와 답글을 저장할 수 있습니다. 마음이 바뀌었다면, 페이지 제목의 오른쪽에 있는 붉은색의 "변경 파기"를 클릭하여 그 동안 작업한 것을 버릴 수 있습니다.</p> + +<p>리비전 답글에서 답글을 달고 <strong>엔터키</strong>를 누르는 것은 "저장하고 계속 수정"하는 것을 클릭하는 것과 같습니다.</p> + +<div class="note"> +<p>변경내용을 저장하려 할 때, 밴경내용이 실제 MDN에는 적절한 내용인데 유효하지 않다는 이유로 거절된다면, <a href="mailto:mdn-spam-watch@mozilla.com?subject=MDN%3A%20Content%20Rejection%20Appeal&amp;body=%3CDescribe%20the%20content%20you%20were%20trying%20to%20save%20and%20where%20you%20were%20trying%20to%20place%20it.%3E">작성팀에 콘텐츠가 게시되게 도와 달라는메일</a>을 보내야만 합니다. </p> +</div> + +<h2 id="새로운_페이지_생성하기">새로운 페이지 생성하기</h2> + +<p>만약 당신이 어디에 새로운 글을 써야할지 모른다고해도 , <strong>걱정하지마세요! </strong>어디든 적으세요 그러면 우리가 그 문서를 찾고 있어야 할 장소로 옴기고 새로 쓴 글이 해당 문서에 적합하다면 , 존재하는 문서에 합칠 거에요. 당신은 또한 완벽하게 해야한다는 것에 대한 걱정을 할 필요가 없어요. 우리는 도움을 주는 행복한 요정들을 가지고 있고 요정들은 당신의 글을 깔끔하고 아주 부드럽게 만드는 것을 도와 줄 것 입니다.</p> + +<p>새로운 페이지를 만드는 몇 가지 방법이 있습니다:</p> + +<ul> + <li><a href="#Missing_page_link">"누락된 페이지" 링크</a></li> + <li><a href="#New_page_without_link">링크가 없는 새로운 페이지</a></li> + <li><a href="#Subpage_of_an_existing_page">이미 존재하는 페이지의 하위 페이지</a></li> + <li><a href="#Clone_of_an_existing_page">이미 존재하는 페이지 복제</a></li> + <li><a href="#Link_from_an_existing_page">이미 존재하는 페이지의 링크</a></li> +</ul> + +<h3 id="페이지_생성_권한_얻기">페이지 생성 권한 얻기</h3> + +<p>보안의 이유로, 새롭게 생성된 계정은 새로운 페이지를 생성할 수 있는 능력이 없습니다. 페이지 생성을 하고 싶다면, 페이지 생성 방법을 안내하는 페이지를 보게 될 것입니다. 두가지 선택이 있습니다.</p> + +<ul> + <li><strong>생성될 페이지 요청</strong>. 이를 위해서는, "Create page:<page title>"이라는 제목으로 <a href="https://bugzilla.mozilla.org/enter_bug.cgi?bug_file_loc=http%3A%2F%2F&bug_ignored=0&bug_severity=normal&bug_status=NEW&cf_fx_iteration=---&cf_fx_points=---&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&flag_type-4=X&flag_type-607=X&flag_type-800=X&flag_type-803=X&form_name=enter_bug&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=Unspecified&priority=--&product=Developer%20Documentation&rep_platform=Unspecified&short_desc=Create%20page%3A%20&status_whiteboard=create-page&target_milestone=---&version=unspecified">문서를 제출</a>합니다. 페이지가 어디에 위치하는지 안다면, MDN에 있는 원하는 페이지의 위치를 URL 항목에 입력합니다. 왜 페이지를 생성해야 하는지에 대한 약간의 정보를 코멘트 텍스트 영역에 입력해야 합니다.</li> + <li><strong>페이지 생성 권한 요청.</strong> 페이지 생성 권한을 요청하면, 부여 받을 것이고, 여기에 있는 지침에 따라 새로운 페이지를 추가할 수 있을 것입니다. 이 특권을 요청하기 위해, <a href="mailto:mdn-admins@mozilla.org">MDN admin 팀에 메일</a>을 보내십시오. 당신의 사용자 이름과 새로운 페이지 생성을 위한 능력을 왜 얻으려 하는지 입력합니다. 예를 들면, 많은 새로운 페이지에 포함되는 새로운 API에 대한 문서를 만들고 있다거나, 새로운 용어를 추가하고 싶을 수 있습니다. 또한, 사이트 콘텐츠에 어떤 유용한 공헌을 이미 했거나, 어느 정도 시간을 할애하여 공헌자로 활동했을 수도 있습니다. 어느 정도의 시간 할애나 다른 요인들이 함께 고려되기 때문에, 정해진 기간이 있는 것은 아닙니다.</li> +</ul> + +<dl> +</dl> + +<h3 id="누락된_페이지_링크">"누락된 페이지" 링크</h3> + +<p>대부분의 위키가 그러하듯, MDN에서도 아직 존재하지 않는 페이지로 링크를 연결하는 것이 가능합니다. 예를 들어, 작성자가 어떤 API의 개별 항목에 대한 페이지를 생성하기 전에, 항목의 모든 리스트를 생성할 수 있습니다. MDN에서 존재하지 않는 페이지로 링크를 연결하면 통상 빨간색으로 표시됩니다.</p> + +<p>"누락된 페이지" 링크로 페이지를 생성하기 위해서는:</p> + +<ol> + <li>MDN에 로그인 합니다. (로그인 하지 않고, "누락된 페이지" 링크를 클릭하면 404(페이지 없음) 에러가 발생합니다.)</li> + <li>"누락된 페이지" 링크를 클릭합니다. <a href="/ko/docs/MDN/Contribute/Editor">MDN 편집기 UI</a>가 열리고, 누락된 페이지를 생성할 수 있는 준비가 됩니다.</li> + <li>페이지의 내용을 작성하고, 저장합니다.</li> +</ol> + +<h3 id="링크가_없는_새로운_페이지">링크가 없는 새로운 페이지</h3> + +<p>다른 페이지의 링크를 걸지 않은 새로운 페이지를 만들기 위해서는, 브라우저의 URL 항목에 고유한 페이지 이름을 입력합니다. 예를 들면, 아래와 같이 입력한다면..</p> + +<pre class="language-html">https://developer.mozilla.org/en-US/docs/FooBar</pre> + +<p>MDN은 제목이 "FooBar"로 된 새로운 페이지가 생성하고, 편집기가 실행되어 새로운 페이지에 내용을 추가할 수 있게 해줍니다. 편집기 모드를 이용하는 방법에 대한 내용은 이 글의 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_and_edit_pages#Editing_an_existing_page">이미 존재하는 페이지 편집하기</a> 섹션을 참고하세요.</p> + +<h3 id="이미_존재하는_페이지의_하위_페이지">이미 존재하는 페이지의 하위 페이지</h3> + +<p>페이지의 계층 구조에서 이미 존재하는 페이지 하위로 페이지를 생성하고 싶다면:</p> + +<ol> + <li>"부모" 페이지에서, <strong>Advanced</strong> 메뉴(툴바의 기어 아이콘)를 클릭하고, <strong>New sub-page</strong>를 클릭합니다. 새로운 문서를 생성하기 위한 편집기 화면이 열립니다.</li> + <li><strong>Title</strong> 항목에 문서의 제목을 입력합니다.</li> + <li>필요하다면 <strong>Slug</strong> 항목을 수정합니다. 예를 들어, 제목이 너무 길어서 단축 URL을 입력할 수 있습니다. 이 항목은 에디터에서 제목의 공백을 언더스코어로 연결하여 자동적으로 채워줍니다. 이 경우, 문서의 URL 중 가장 마지막 부분만 수정할 수 있습니다.</li> + <li>TOC 항목에서, 페이지의 목차에 자동적으로 노출되기 원하는 헤드라인을 선택하거나, 페이지에서 필요가 없다면 "목차 없음(No table of contents)"을 선택합니다.</li> + <li>편집 패널에서 페이지의 내용을 작성하고 변경사항을 저장합니다. 편집 모드 사용에 대한 방법은 이 글의 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_and_edit_pages#Editing_an_existing_page">이미 존재하는 페이지 편집하기</a> 섹션을 참고하세요.</li> +</ol> + +<h3 id="이미_존재하는_페이지_복제">이미 존재하는 페이지 복제</h3> + +<p>새로운 페이지를 위해 사용하고자 하는 페이지의 포멧이 이미 존재한다면, 페이지를 '복제'하여 내용을 수정할 수 있습니다.</p> + +<ol> + <li>복제하려는 원래 페이지에서, <strong>Advanced</strong> 메뉴(툴바의 기어 아이콘)을 클릭하고, 이 페이지 복제하기(<strong>Clone this page</strong>)를 클릭합니다. 새로운 문서를 생성하기 위한 편집기 화면이 열립니다.</li> + <li>페이지의 타이틀(<strong>Title</strong>)을 새로운 내용에 맞게 적절하게 바꿉니다. <strong>Slug</strong> 항목은 타이틀(<strong>Title</strong>) 항목을 바꾸면 자동적으로 반영됩니다.</li> + <li>필요하다면, 문서의 계층구조의 다른 부분에 새로운 문서를 넣기 위해 <strong>Slug</strong> 항목의 경로 부분도 변경합니다. (대부분의 경우, 복제된 페이지가 원래 페이지와 유사한 내용을 가지고 있고, 따라서 위치도 비슷하기 때문에 이 과정은 필요하지 않습니다.)</li> + <li>TOC 항목에서, 페이지의 목자에 자동적으로 노출되기 원하는 헤드라인을 선택하거나, 목차를 가지고 있지 않다면 "목차 없음(No table of contenst)"을 선택합니다.</li> + <li>편집 패널에서 페이지의 내용을 작성하고, 변경사항을 저장합니다. 편집 모드 사용에 대한 방법은 이 글의 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_and_edit_pages#Editing_an_existing_page">이미 존재하는 페이지 편집하기</a> 섹션을 참고하세요.</li> +</ol> + +<h3 id="이미_존재하는_페이지의_링크">이미 존재하는 페이지의 링크</h3> + +<p>이 방법은 다소 복합적입니다. 다른 페이지에 링크를 만들고, 새로운 페이지를 만들기 위해 삽입한 링크를 클릭합니다.</p> + +<ol> + <li>이미 존재하는 페이지의 텍스트 안에 넣고자 하는 새로운 페이지의 이름을 입력합니다.</li> + <li>이름을 선택하고, 편집기의 툴바에서 링크 아이콘 클릭(<strong>click the Link icon (<img alt="" src="https://developer.mozilla.org/files/3810/link-icon.png">)</strong>)을 클릭합니다. "<strong>Update Link</strong>" 다이얼로그가 열리고, "<strong>Link To</strong>" 항목에 선택된 텍스트로 채워집니다.</li> + <li>기본적으로, URL 항목의 시작 부분은 "/en-US/docs/"가 삽입됩니다. <em> </em>"/en-US/docs/" 다음에 페이지의 이름을 입력하세요. (페이지 이름은 링크 텍스트와 동일하지 않아도 됩니다.)</li> + <li>링크를 생성하고 삽입하기 위해 OK를 클릭합니다.</li> +</ol> + +<p>페이지가 존재하지 않는다면, 링크는 붉은색으로 보여집니다. 페이지가 존재한다면 링크는 파란색으로 보여집니다. 새로운 페이지를 만들고 싶은데 원하는 페이지 제목이 이미 존재한다면, 먼저 해당 페이지에 있는 내용을 추가 편집하거나 좀 더 개선할 부분은 없는지 확인하십시오. 아니면, 생성하고자 하는 페이지에 대한 다른 제목을 고민해보고 링크를 만들어 보세요. 페이지 이름에 대한 안내는 <a href="https://developer.mozilla.org/ko/docs/Project:Page_Naming_Guide">페이지 네이밍 가이드</a>를 참고하세요.</p> + +<p>새로운 페이지에 내용을 추가하기 위해, 저장하고 편집기를 닫은 후에 이제 막 추가된 붉은색 링크를 클릭합니다. 편집 모드에 새로운 페이지가 열리고, 작성을 할 수 있습니다. 편집 모드 사용에 대한 방법은 이 글의 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_and_edit_pages#Editing_an_existing_page">이미 존재하는 페이지 편집하기</a> 섹션을 참고하세요.</p> + +<h2 id="페이지_콘텐츠_새로고침하기">페이지 콘텐츠 새로고침하기</h2> + +<p>MDN의 KumaScript 매크로와 페이지의 콘텐츠를 다른 페이지로 넣을 수 있는 트랜스클루젼(transclusion)의 지원은 성능 향상을 위해 생성된 페이지의 캐시의 필요에 의해 종종 방해될 수 있다. 페이지는 그 소스로부터 만들어지고, 이후에 있을 요청을 위해 산출물을 캐시로 저장해둔다. 그 때부터 어떤 매크로(템플릿), 페이지의 <a href="https://developer.mozilla.org/en-US/docs/Template:Page">Page</a> 매트로를 이용하는 트랜스클루젼도 매크로나 매크로의 산출물, 혹은 삽입되어 추가된 원래 자료의 변경에도 영향이 없을 것이다.</p> + +<ul> + <li>페이지를 직접 업데이트 하기 위해서, 브라우저의 강재 새로고침을 이용할 수 있다. MDN은 이를 감지하여 업데이트된 매크로 산출물과 삽입된(transcluded) 페이지 내용을 가져와 페이지를 새롭게 만든다.</li> + <li> 정기적으로 페이지가 자동으로 새롭게 만들어지도록 설정하는 것도 가능하다. 페이지가 자주 업데이트 되는 것에 대한 기대가 없다면 이것은 실행되지 않을 것입니다. 자세한 내용은 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Tools/Page_regeneration">페이지 재생성</a>을 참고하세요. </li> +</ul> + +<h2 id="함께_보기">함께 보기</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN 편집기 가이드</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Content/Style_guide">MDN 스타일 가이드</a></li> +</ul> diff --git a/files/ko/mdn/contribute/does_this_belong/index.html b/files/ko/mdn/contribute/does_this_belong/index.html new file mode 100644 index 0000000000..46f6395a52 --- /dev/null +++ b/files/ko/mdn/contribute/does_this_belong/index.html @@ -0,0 +1,139 @@ +--- +title: 이건 MDN에 있나요? +slug: MDN/Contribute/Does_this_belong +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>무엇인가를 문서로 남겨두겠다는 생각을 하기 시작했다면, 그 문서를 어디에 둘지도 고민해보았을 겁니다. 문서가 위치할 수 있는 몇 가지 장소가 있고, MDN이 웹에서 가장 큰 문서 저장소 중 하나이지만 유일한 옵션은 아닙니다. 또한 소스 코드에 문서를 보관해둘 수도 있고, <a href="https://wiki.mozilla.org/">Mozilla 위키</a>나 git 저장소의 README 파일에 저장해 두어도 좋습니다. 이 글에서는 어느 방법이 여러분들의 문서와 어울릴지를 판단하는데 도움이 되기 위해서 쓰였습니다.</p> + +<h2 id="MDN에는_뭐가_있죠">MDN에는 뭐가 있죠?</h2> + +<p>우리는 MDN에 정말 다양한 주제를 다룹니다. 하지만 완전히 MDN에 있어서는 안될 몇 가지도 있습니다. 이 섹션은 여러분의 문서가 MDN에 있어도 괜찮은지 판단할 수 있도록 도와주겠습니다.</p> + +<h3 id="MDN에서_다루는_것">MDN에서 다루는 것</h3> + +<p>우리는 MDN에서 정말 많은 내용을 다루고 있습니다. 일반적으로 완전히 제작되었거나 배포 중인 Mozilla 제품이나, 웹에 공개된 열린 기술이라면, MDN에 문서로 남겨둡니다.</p> + +<p>우리들이 다루고 있는 내용 몇가지를 맛보기로 보여드리겠습니다. 전체 리스트는 아니지만 몇가지 아이디어는 줄 수 있을 겁니다.</p> + +<ul> + <li>열린 웹 기술 + <ul> + <li>HTML</li> + <li>CSS</li> + <li>JavaScript</li> + <li>Web에 공개된 API</li> + <li>그 외 기타</li> + </ul> + </li> + <li>Firefox OS + <ul> + <li>오픈 웹 애플리케이션</li> + <li>Firefox OS 빌드하고 설치하기</li> + <li>Firefox OS 프로젝트에 기여하기</li> + <li>Gaia 설정 변경하기</li> + <li>그 외 기타</li> + </ul> + </li> + <li>Mozilla 플랫폼 + <ul> + <li>Gecko</li> + <li>Firefox를 빌드하고 설정하기</li> + <li>XUL</li> + <li>XPCOM</li> + <li>그 외 기타</li> + </ul> + </li> +</ul> + +<div class="note"> +<p><strong>참고하세요:</strong> 우리는 Mozilla 기술이 아니더라도 Web에 공개되어 있는 한 다룰 수 있다는 점이 중요합니다. 가령, 우리는 Webkit 전용 CSS 프로퍼티를 설명해놓은 문서도 있습니다.</p> +</div> + +<h3 id="우리가_다루지_않는_것">우리가 다루지 않는 것</h3> + +<p>MDN에 문서로 남겨져서는 안되는 명백한 것인지 아닌지에 대해 스스로 질문해볼 수 있습니다.</p> + +<ul> + <li>아직 계획중인 문서인가?</li> + <li>아직 존재하지 않는 기술을 설명해놓은 설계 문서인가?</li> + <li>프로젝트를 제안하는 문서인가?</li> + <li>단순히 기술 스펙만 나열했는가?</li> + <li>Mozilla 브라우저가 아닌 특정 브라우저에만 사용되는 웹에 노출되지 않은 기술인가?</li> +</ul> + +<p>저 질문 중 하나라도 "예"라고 답변할 수 있다면, MDN에 있어서는 안될 문서입니다. 저 질문 모두에 "아니요"라고 대답할 수 있다면, MDN에 문서로 보관할지 진지하게 고민할 때가 되었다는 겁니다!</p> + +<h2 id="MDN에_문서로_남겨두면_좋은_점">MDN에 문서로 남겨두면 좋은 점</h2> + +<p>MDN에 문서로 남겨두면 좋은 점이 굉장히 많답니다.</p> + +<h3 id="글을_쓰는_사람들이_굉장히_많습니다">글을 쓰는 사람들이 굉장히 많습니다</h3> + +<p>MDN 공동체는 굉장히 큽니다. 정말 큽니다. 큰 것들을 작게 보이게 만들 정도로 큽니다. 농담이 아니라, 우리는 굉장히 많은 사람들과 MDN에 있는 자료를 만들어내며 관리하고 있습니다. 전세계 모든 땅(인정할게요. 남극까지는 잘 모르겠어요.)의 작가, 편집자들과 함께하고 있기 때문에, 글을 쓰려는 사람들은 무조건 득 보는 거에요.</p> + +<ul> + <li>우리에게는 우리의 컨텐츠를 최대한 좋게 만들어 보겠다는 <strong>사명</strong>을 갖고 있는 유급 편집 스탭이 있습니다.</li> + <li>우리는 충분한 양의 컨텐츠를 기여하고 여러분들을 도와줄 수 있는 핵심 커뮤니티와 함께하고 있습니다.</li> + <li><strong>사실은 다른 사람들에게 여러분의 글의 대부분 혹은 전부를 쓰게 할 수 있는 절호의 찬스입니다!</strong></li> + <li>넓디넓은 MDN 커뮤니티에게서 많은 것들을 얻어갈 수 있습니다. 오타를 잡아주는 것부터 시작해서 편집에 관한 논평까지, 여러분들의 소원을 들어줄 수 있습니다.</li> + <li>{{IRCLink("mdn")}} 채널을 통해 글쓰기 커뮤니티와 이야기를 하거나 조언을 들을 수 있고, 여러분들의 문서 제작이나 유지보수에 도움을 청할 수도 있습니다</li> + <li>전세계에 분포한 기여자들과 함께하고 있기 때문에, 언제나 누군가 주변에서 문제를 발견하고 해결해 줄 겁니다.</li> +</ul> + +<p>Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.</p> + +<h3 id="유지보수">유지보수</h3> + +<p>Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:</p> + +<dl> + <dt>스팸 제거</dt> + <dd>스팸이 발생하면 우리들이 처리합니다.</dd> + <dt>편집</dt> + <dd>여러분 생각보다 필력이 달려도 걱정하실 것 없습니다. 여러분이 쓴 글을 다른 사람들이 읽을 수 있도록 해주겠습니다.</dd> + <dt>스타일의 일관성</dt> + <dd>여러분이 작성한 문서 하나에서만 지켜지는 일관성이 아니라, 다른 문서와 함께 있을 때에도 일관적인 스타일을 가지고 있을지 봐주겠습니다.</dd> + <dt>컨텐츠 관리</dt> + <dd>Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.</dd> +</dl> + +<h2 id="다른_곳에_문서로_남겨두는_경우">다른 곳에 문서로 남겨두는 경우</h2> + +<p>MDN 말고 다른 곳에다가 여러분이 만든 작업물을 문서로 남겨둘 이유도 없는 건 아닙니다. 그런 이유에 대해서 몇가지 살펴보도록 하고, 각각 장단점을 찾아보도록 할게요.</p> + +<h3 id="계획이나_진행_상황">계획이나 진행 상황</h3> + +<p>간단합니다. 계획, 진행 상황, 요청에 대한 문서는 MDN에 남기면 안됩니다.</p> + +<h3 id="Github에_올라온_프로젝트">Github에 올라온 프로젝트</h3> + +<p>Mozilla의 몇몇 프로젝트는 Github에 올라와 있습니다. 또, Github에는 문서를 보관하기 위해 자기네들만의 위키 비스무리한 시스템을 가지고 있어요. 몇몇 팀은 거기에다가 문서를 남겨두기를 더 좋아합니다. 여러분만의 문서를 만들어갈 생각이라면 아무래도 그쪽이 더 편하고 좋겠죠. 하지만 몇가지 사실을 기억하세요.</p> + +<ul> + <li>MDN 문서 팀이 여러분들을 도와드릴 수 없을지도 모릅니다. 우리는 일반적으로(때로 예외가 있기는 합니다만) MDN 바깥의 문서화에는 참여하지 않습니다.</li> + <li>여러분들의 문서다 다른 관련된 내용과 상호 링크하기가 힘들거나 불가능합니다.</li> + <li>다른 문서와 일관된 스타일을 가지지 못할 수도 있습니다.</li> + <li>다른 문서 사이에 없기 때문에 발견될 가능성이 줄어듭니다.</li> + <li>Github에 저장된 문서는 MDN에 있는 문서에 비해 별로 매력적으로 보이지도 않으면서 가독성도 영 좋지는 않습니다.</li> +</ul> + +<p>물론 이런 점들이 여러분들에게 별로 문제가 되지 않거나 문제가 되더라도 딱히 불편한 점이 없을 수도 있습니다. 몇몇 팀은 문서로 남기겠다는 필요성이 별로 없어서 코드 안에서만 작업하고 문서를 남겨두기도 합니다.</p> + +<h3 id="소스_안에_문서를_남겨두고_싶은_경우">소스 안에 문서를 남겨두고 싶은 경우</h3> + +<p>몇몇 팀은 소스 저장소에다가 자신들의 문서를 저장하는 걸 더 선호하기도 합니다. 내부 프로젝트나 라이브러리 프로젝트에서는 꽤나 흔한 일이긴 한데요. 코드를 쓰듯이 자신들의 기술을 문서로 남길 수 있다는 점에서 이점이 있기는 합니다. 하지만 그만큼 단점도 있지요.</p> + +<ul> + <li>MDN 문서 팀이 여러분들을 도와드릴 수 없습니다. 코드가 Mozilla의 소스 저장소에 있더라도, 리뷰나 체크인 시스템은 문서 팀이 참여하기에는 그닥 효율적이지 못합니다.</li> + <li>관련 있는 다른 문서와 상호 링크할 수 있는 간편한 도구를 찾기가 힘듭니다. 상호 링크를 하면 읽는 이들에게 맥락과 중요한 정보를 더 잘 전달할 수 있을텐데 말이죠.</li> + <li>다른 문서 사이에 없기 때문에 발견될 가능성이 줄어듭니다.</li> + <li>(JavaDoc 같은) 변환 도구를 사용하여 웹에서 읽을 수 있는 문서를 만들더라도, MDN에서 할 수 있는것보다 예쁘거나 매력적이지도 않을 겁니다.</li> +</ul> + +<p>여전히 몇몇 프로젝트에서 이런 방법을 사용할 수 없는 건 아닙니다. (오히려 좋은 방법일 수도 있습니다.) 작은 프로젝트나 별로 관심을 얻을 생각을 하지 않는 프로젝트에는 특히 그렇죠.</p> + +<h2 id="나중에는">나중에는</h2> + +<p>It's worth mentioning that someday we intend to make it possible to present off-site content as if it were part of MDN, and that we hope to one day have tools to actually import content from other sites onto MDN. However, there's no timeline in place for making this happen, and even once it does, it will not be as effective as building the documentation directly on MDN.</p> diff --git a/files/ko/mdn/contribute/feedback/index.html b/files/ko/mdn/contribute/feedback/index.html new file mode 100644 index 0000000000..321efa3330 --- /dev/null +++ b/files/ko/mdn/contribute/feedback/index.html @@ -0,0 +1,74 @@ +--- +title: MDN에 피드백을 보내주세요! +slug: MDN/Contribute/Feedback +tags: + - MDN + - MDN 메타 + - 가이드 + - 문서 +translation_of: MDN/Contribute/Feedback +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>Mozilla 개발자 네트워크에 오신것을 환영합니다! <span class="seoSummary"> 만일 당신이 MDN을 사용하면서 발견한 문제점들이나 바라는 점들을 제안하고 싶다면 이곳은 당신에게 어울리는 장소입니다. 당신이 피드백을 제공함으로써 당신의 Mozilla 커뮤니티에서의 힘은 더 커질 것이고 우리는 당신의 관심에 감사드릴 것입니다.</span></p> + +<p><span class="seoSummary">당신에게는 당신의 통찰력을 제공하기 위한 몇가지 선택사항들이 있으며 이 문서는 당신에게 도움을 줄 것입니다.</span></p> + +<h2 id="자료_업데이트하기">자료 업데이트하기</h2> + +<p>당신이 문서에서 문제점을 찾았다면, 그냥 고치면 됩니다. </p> + +<ol> + <li><a href="https://github.com/">Github</a>을 이용해서 <a href="/ko/docs/MDN/Contribute/Howto/Create_an_MDN_account">계정을 만들고</a></li> + <li>원하는 페이지에서 파란색 <strong>편집</strong> 버튼을 클릭해서 에디터를 엽니다.</li> + <li>변경이 끝나면 <strong>게시</strong> 버튼을 클릭합니다. </li> +</ol> + +<p>문서는 모두 위키 기반이며 자원봉사자들과 스탭들이 관리하므로 문법적인 것에 너무 부담가질 필요 없습니다. 실수가 있다면 우리가 고칠 겁니다. 걱정하지 마세요.</p> + +<p>MDN 문서작성에 도움을 주는 방법을 알고싶다면 :</p> + +<ul> + <li><a href="/ko/docs/Project:Getting_started" title="/en-US/docs/Project:Getting_started">시작하기</a></li> + <li><a href="/ko/docs/MDN/Contribute">MDN에 도움주기</a></li> + <li><a href="/ko/docs/MDN/Contribute/Editor" title="/en-US/docs/Project:MDN_editing_interface">MDN 편집 인터페이스</a></li> +</ul> + +<h2 id="대화에_참여하기">대화에 참여하기</h2> + +<p>우리랑 대화하세요! MDN 콘텐츠에 일하는 다른 사람들과 연락하는 몇가지 방법이 여기 있습니다.</p> + +<h3 id="채팅실시간">채팅(실시간)</h3> + +<p>우리는 MDN과 콘텐츠에 대한 의견을 <a href="https://wiki.mozilla.org/IRC">IRC</a>를 통해서 나눕니다. 당신도 참여하세요! 주제별로 몇가지 채널이 있습니다. </p> + +<dl> + <dt><a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/mdn">MDN 사이트 콘텐츠 (#mdn)</a></dt> + <dd>사이트 이용법, 콘텐츠 읽는 법, 기여하는 방법 등에 대한 MDN의 일반적인 논의를 합니다. 콘텐츠에 대한 질문이나 덧붙일 말이 있을 때, 기고문을 작성하거나, 그냥 작성팀과 이야기하고 싶을 때 이곳을 이용합니다. </dd> + <dt><a href="irc://irc.mozilla.org/mdndev" title="irc://irc.mozilla.org/mdndev">문서 사이트 개발 (#mdndev)</a></dt> + <dd>{{IRCLink("mdndev")}} 채널은 MDN 사이드가 동작하는 플랫폼 개발작업에 대해 이야기하는 곳입니다. 사이트 동작에 문제를 겪었거나 신규 기능에 대한 아이디어가 있다면 이곳을 찾으세요. </dd> +</dl> + +<h3 id="토론_비동기">토론 (비동기)</h3> + +<p>장기 토론은 <a href="https://discourse.mozilla-community.org/c/mdn">MDN 토론 포럼</a> 을 사용합니다. 이메일(<a href="mailto://mdn@mozilla-community.org">mdn@mozilla-community.org</a>)을 통해서 포럼에 게시물을 올릴 수 있습니다. 포럼에 합류하면 이메일로 토론 알림을 받을건지 선택할 수 있습니다. </p> + +<h2 id="문제_보고하기">문제 보고하기</h2> + +<h3 id="문서_오류">문서 오류</h3> + +<p>당신이 문서 오류를 발견했는데 수정할 수 없다면, <a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md&projects=mdn/sprints/2&labels=user-report">신고</a>하면 됩니다! 모든 종류의 문서 오류가 해당됩니다. 예를 들면</p> + +<ul> + <li>단순 교정</li> + <li>완전히 새로운 항목 요청</li> + <li>잘못된 콘텐츠 신고 (악성광고, 잘못 붙인 번역)</li> +</ul> + +<p>위에서도 말한 것 처럼, 우리는 당신이 직접 기여하기를 원합니다. 하지만 신고만해도 괜찮습니다. </p> + +<h3 id="사이트_오류">사이트 오류</h3> + +<p>MDN 사이트의 문제점을 겪었거나, 신규기능의 아이디어가 있다면 <a href="https://bugzilla.mozilla.org/form.mdn">MDN 개발팀으로 이슈 티켓을 끊어주세요</a>. </p> diff --git a/files/ko/mdn/contribute/getting_started/index.html b/files/ko/mdn/contribute/getting_started/index.html new file mode 100644 index 0000000000..23e4774d1d --- /dev/null +++ b/files/ko/mdn/contribute/getting_started/index.html @@ -0,0 +1,111 @@ +--- +title: MDN 시작하기 +slug: MDN/Contribute/Getting_started +tags: + - MDN 메타 + - 가이드 + - 공헌하기 + - 기여하기 + - 도움말 + - 시작하기 + - 초보자 +translation_of: MDN/Contribute/Getting_started +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p id="What_is_MDN.3F"><span class="seoSummary">우리는 어떤 브랜드의 플랫폼이나 브라우저에 상관 없이 더 나은 웹을 위한 리소스를 만드는 오픈 커뮤니티입니다. 누구나 참여할 수 있고, 여러분의 참여는 우리에게 더욱 큰 힘이 됩니다. 우리는 가장 멋진 것들을 제공하기 위해 계속해서 웹의 혁신을 이끌어 낼 것입니다. 여러분들과 함께 말이죠.</span></p> + +<p><span>MDN의 모든 것, 이를테면 문서, 데모, 사이트 등은 모두 열린 커뮤니티의 개발자들에 의해 만들어 집니다. 지금 바로 참여하세요!</span></p> + +<h2 id="MDN에_참여하기_3단계"><span>MDN에 참여하기 3단계</span></h2> + +<p>MDN은 <strong>누구나</strong> 문서를 추가하고 수정할 수 있는 위키입니다. 기술에 대한 방대한 지식을 알아야 한다거나, 프로그래머가 아니더라도 됩니다. 단순히 교정이나 문자를 수정하는 일부터 API 문서를 작성하는 일까지 우리가 할 수 있는 일이 풍부하게 준비되어 있습니다.</p> + +<p>기여하기는 쉽고, 안전합니다. 만약 실수를 하더라도, 쉽게 고칠 수 있습니다. 만약 문법을 잘 몰라서 문장이 틀리더라도 걱정하지 마세요. 우리에겐 MDN에 있는 콘텐츠를 가능한 한 좋게 만드는 팀이 있습니다. 우리에게 부족한 점이 있더라도 누군가 우리의 부족한 점을 채워 줄 것입니다. 우리는 우리가 알고 있는 것과, 우리가 잘하는 것에 집중하면 됩니다.</p> + +<h3 id="Step_1_MDN_계정_만들기">Step 1: MDN 계정 만들기</h3> + +<p>MDN에 참여하기 위해서는 반드시 MDN 계정을 생성해야합니다. <a href="/ko/docs/MDN/Contribute/Howto/Create_an_MDN_account">계정을 만드는 방법</a>에서 자세한 내용을 확인하세요. 참고로 MDN 계정을 만들려면 <a href="https://github.com/join">Github 계정이 필요합니다</a>. 인증에 Github을 사용하고 있습니다. </p> + +<p>신규 문서를 만들고 싶다면 {{SectionOnPage("/ko/docs/MDN/Contribute/Howto/Create_and_edit_pages", "문서 생성 권한 얻기")}}를 참고하세요. 문서를 만드는 권한에 대한 중요 정보가 있습니다. 보안상의 이유로 신규 계정은 문서를 만들 수 없습니다. </p> + +<h3 id="Step_2_할_일_정하기">Step 2: 할 일 정하기</h3> + +<p>로그인 하셨다면, <a href="#할_수_있는_일의_종류">아래의 리스트</a>에서 다양한 작업의 종류의 설명을 읽어보시고 가장 마음에 드시는 것을 고르세요. 작업을 선택하는데 있어 어떠한 제약도 없습니다.</p> + +<h3 id="Step_3_작업하기">Step 3: 작업하기</h3> + +<p>어떤 일을 할지 결정했다면 특정 페이지나 코드 등 마음에 드는 것을 선택해서 바로 시작하세요!</p> + +<p>완벽하지 않아도 괜찮습니다. 오류가 있다면 다른 MDN 공헌자들이 고칠 것입니다. 궁금한 점은 <a href="/ko/docs/MDN/Community">커뮤니티</a> 페이지의 메일링 리스트나 채팅 채널에서 답을 얻을 수도 있습니다.</p> + +<div class="note"> +<p><strong>참고</strong>: 수정된 내용을 "실제로" 반영하기 위함이 아닌, 실험을 하고 싶다면 "<a href="/ko/docs/Sandbox">샌드박스</a>" 페이지를 이용하세요. 이 페이지는 반드시 필요한 내용이 아니라면 수정하지 마세요. 단순히 어떤 일이 일어나는지 보려고 불필요한 변경을 하는 것은 다른 공헌자들에게 혼란을 줄 수 있습니다.</p> +</div> + +<p>작업을 모두 마쳤다면, 다른 작업을 자유롭게 고르거나 아래의 <a href="#Other things you can do on MDN">MDN에서 할 수 있는 다른 일</a>을 살펴보세요.</p> + +<h2 id="할_수_있는_일의_종류"><a name="Possible task types">할 수 있는 일의 종류</a></h2> + +<p>당신의 능력과 관심에 따라 MDN에 기여할 수 있는 다양한 방법들이 있습니다. 일부 작업들은 어렵게 느껴질 수도 있지만, 5분도 안되는 작은 시간으로 간단히 끝낼 수 있는 작업들이 많이 있습니다! 작업에 대한 간단한 설명을 통해 작업 유형 별로 대략적인 소요 시간을 알 수 있을 것입니다.</p> + +<h3 id="1번_글_쓰는게_좋아요">1번: 글 쓰는게 좋아요</h3> + +<p>문서를 검토하거나 수정하고 올바른 태그를 적용할 수 있습니다.</p> + +<ul> + <li><a href="/ko/docs/MDN/Contribute/Howto/Set_the_summary_for_a_page">페이지 요약 달기</a> (5-15분)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Do_an_editorial_review">수정사항 리뷰</a> (5-30분)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary">용어사전에 항목 추가하기<sup>(en)</sup></a> (15분-1시간)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web">사람들이 웹에 대해 배울 수 있는 글쓰기<sup>(en)</sup></a> (1-3시간)</li> +</ul> + +<div class="note"><strong>참고:</strong> 기존 글을 수정하거나 새로운 내용을 작성하고 있다면 <a href="/ko/docs/Project:MDN/Style_guide">스타일 가이드</a>를 준수하고 있는지 확인하세요. 문서들의 일관성을 유지하기 위함입니다.</div> + +<h3 id="2번_코드_쓰는게_좋아요">2번: 코드 쓰는게 좋아요</h3> + +<p>샘플 코드를 만들어주세요! 아니면 <a href="https://developer.mozilla.org/ko/docs/Project:MDN/Kuma">Kuma</a> 사이트 플랫폼을 구축이나 브라우저 호환성 데이터 구축을 도와주세요. </p> + +<ul> + <li><a href="/ko/docs/MDN/Contribute/Howto/Convert_code_samples_to_be_live">"동작하는" 코드 샘플로 변환하기</a> (30분)</li> + <li><a href="https://wiki.mozilla.org/Webdev/GetInvolved/developer.mozilla.org">개발자 그룹에 참여하기 읽기</a> (30분)</li> + <li><a href="http://kuma.readthedocs.org/en/latest/installation.html">Kuma 빌드 환경 설정</a> (1시간)</li> + <li><a href="https://github.com/mozilla/kuma#readme">수정된 코드를 Kuma 코드베이스로 보내기 </a>(1시간)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Add_or_update_browser_compatibility_data">브라우저 호환성 데이터 갱신하기</a> (30분)</li> +</ul> + +<h3 id="3번_글도_코드도_쓰는거라면_뭐든_좋아요">3번: 글도 코드도 쓰는거라면 뭐든 좋아요</h3> + +<p>새로운 글을 작성하거나, 기술적 정확성을 검토하기 또는 문서를 각색하기와 같은 기술적이고 언어적 스킬이 모두 요구되는 작업들이 있습니다.</p> + +<ul> + <li><a href="/ko/docs/MDN/About/Promote">여러분의 웹사이트에 MDN 홍보하기</a> (5분)</li> + <li>더이상 사용하지 않는 <a href="/ko/docs/MDN/Contribute/Howto/Remove__Experimental__Macros">"실험적인" 메크로 제거하기</a> (5-30분)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Do_a_technical_review">기술 리뷰</a> (30분)</li> + <li><a href="/ko/docs/MDN/Contribute/Contribute_to_docs_that_are_currently_needed">주요한 주제에 해대 새로운 글 작성 </a>(1시간 이상)</li> + <li><a href="/ko/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">사람들이 웹 학습에 도움을 줄 상호작용하는 예제 작성</a> (1시간 이상)</li> + <li><a href="http://www.joshmatthews.net/bugsahoy/?mdn=1">Bugs Ahoy의 MDN 카테고리</a>에 <a href="/ko/docs/MDN/Contribute/Howto/Resolve_a_mentored_developer_doc_request">문서 버그 고치기</a> (1시간 이상)</li> +</ul> + +<h3 id="4번_우리말로_MDN을_보고_싶어요">4번: 우리말로 MDN을 보고 싶어요</h3> + +<p>MDN의 모든 현지화 및 번역 작업들은 우리의 멋진 자원 커뮤니티가 수고해 주셨습니다.</p> + +<ul> + <li><a href="/ko/docs/MDN/Contribute/Localize/Translating_pages">페이지 번역하기</a> (2시간) (<a href="/ko/docs/MDN/Doc_status/l10nPriority">주요 페이지 현황</a>)</li> + <li><a href="/ko/docs/MDN/Contribute/Localize/Localization_projects">지역화 프로젝트</a>에 올라온 다른 참여자들과 소통하기 (30분)</li> +</ul> + +<h3 id="5번_잘못된_점은_찾았는데_어떻게_고쳐야_할_지_모르겠어요">5번: 잘못된 점은 찾았는데, 어떻게 고쳐야 할 지 모르겠어요</h3> + +<p><a class="external" href="https://bugzilla.mozilla.org/form.doc">문서 버그 신고</a>를 작성해서 문제를 보고할 수 있습니다. (5분)</p> + +<h2 id="MDN에서_할_수_있는_다른_일"><a name="Other things you can do on MDN">MDN에서 할 수 있는 다른 일</a></h2> + +<ul> + <li><a href="/ko/docs/MDN/Community">MDN 커뮤니티에 가입</a>하세요.</li> + <li>다른 사람들이 당신에 대해 더 많이 알 수 있도록 <a href="/ko/profile">프로필을 작성</a>해보세요.</li> + <li><a href="/ko/docs/MDN/Contribute">MDN에 기여하는 법</a>에 대해서 더 자세히 알아보세요.</li> +</ul> diff --git a/files/ko/mdn/contribute/howto/do_a_technical_review/index.html b/files/ko/mdn/contribute/howto/do_a_technical_review/index.html new file mode 100644 index 0000000000..9b648a8d0c --- /dev/null +++ b/files/ko/mdn/contribute/howto/do_a_technical_review/index.html @@ -0,0 +1,41 @@ +--- +title: 기술 리뷰를 하는 방법 +slug: MDN/Contribute/Howto/Do_a_technical_review +translation_of: MDN/Contribute/Howto/Do_a_technical_review +--- +<div>{{MDNSidebar}}</div><p class="summary">기술 리뷰는 기술적 정확성과 글의 완결성을 검토하는 것, 필요하다면 수정하는 것으로 이루어집니다. 글의 작성자가 다른 사람이 글의 기술적 내용을 확인하는 것을 바란다면, 작성자는 편집을 하는동안 "Technical review" 체크박스에 체크합니다. 작성자는 대개 기술 리뷰를 위해 특정한 엔지니어와 접촉하지만, 해당 주제에 대한 전문가라면 누구라도 가능합니다.</p> +<p><span class="seoSummary">이 글은 기술 리뷰를 어떻게 하는지에 대해 기술하고, 그에 따라서 MDN의 컨텐츠들이 정확하도록 도움을 줍니다.</span></p> +<table class="fullwidth-table"> + <tbody> + <tr> + <td><strong>어떤 부분에 이 일이 필요하나요?</strong></td> + <td><a href="/en-US/docs/needs-review/technical">technical review</a>가 필요하다고 표시된 특정 글</td> + </tr> + <tr> + <td><strong>이 일을 하기 위해 무엇을 알아야 하나요?</strong></td> + <td> + <ul> + <li>리뷰를 하고 있는 글의 주제에 대한 전문 지식.</li> + <li>MDN의 위키 글을 편집할 수 있는 능력.</li> + </ul> + </td> + </tr> + <tr> + <td><strong>어떤 단계를 거쳐야 하나요?</strong></td> + <td> + <ol> + <li><a href="/en-US/docs/needs-review/technical">technical reviews</a>가 필요한 페이지 목록으로 갑니다. 기술 리뷰가 요청된 모든 페이지들이 보여집니다.</li> + <li>친숙한 주제를 가진 페이지를 고르세요.</li> + <li>링크를 클릭하여서 페이지를 부르세요.</li> + <li>페이지가 불려지면, 최상단 근처의 <strong>EDIT</strong> 버튼을 클릭하세요; MDN 에디터로 갑니다. 처음에 고른 페이지가 당신한테 맞지 않는다면 다른 페이지로 바꾸는 것을 주저하지 마세요.</li> + <li>글을 읽으면서 틀린 기술 정보를 고치고 빠진 중요한 정보를 추가하세요.</li> + <li>글 아래에 당신이 한 일에 대해서 기술하는 다음과 같은 코멘트를 입력하세요, '<em>기술 리뷰 완료.</em>' 정보를 수정한다면, 그것을 코멘트에 포함시키세요, 예를 들어 <em>'기술 리뷰: fixed parameter descriptions.'</em></li> + <li><strong>SAVE CHANGES</strong> 버튼을 클릭하세요 .</li> + <li>에디터를 닫고 난 후 올바른 글이 화면에 뜨고 나면, 측면의 <strong>Technical</strong> 엔트리를 체크하여 (<strong>다음</strong><b>의 리뷰가 요청되었습니다 </b>아래) <strong>SUBMIT REVIEW </strong>버튼을 클릭하세요.</li> + <li>끝났습니다!</li> + </ol> + </td> + </tr> + </tbody> +</table> +<p> </p> diff --git a/files/ko/mdn/contribute/howto/do_an_editorial_review/index.html b/files/ko/mdn/contribute/howto/do_an_editorial_review/index.html new file mode 100644 index 0000000000..13b2f0d4a1 --- /dev/null +++ b/files/ko/mdn/contribute/howto/do_an_editorial_review/index.html @@ -0,0 +1,48 @@ +--- +title: 편집 검토를 하는 방법 +slug: MDN/Contribute/Howto/Do_an_editorial_review +translation_of: MDN/Contribute/Howto/Do_an_editorial_review +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ko-KR/docs/MDN")}}</div> + +<p class="summary"><strong>편집자 검토</strong>는 글의 오타와 맞춤법, 문법, 단어의 용법, 또는 원문의 오류를 고치는 일입니다. 모든 공헌자분들은 자신의 지식을 사용해 유용하고 가치있는 글을 만드는 데 기여하고 있습니다만, 이분들이 모두 어학전문가는 아닙니다. 따라서 언어적인 측면에서 교열과 교정이 종종 필요해집니다. 이 교열과 교정 작업이 바로 편집자 검토입니다.</p> + +<p><span class="seoSummary">이 글은 어떻게 편집자 검토를 수행하는지, 그리하여 MDN 컨텐츠들의 정확도를 높일 수 있게 되는 지에 대해 설명합니다.</span></p> + +<dl> + <dt>편집자 검토는 어떤 일입니까?</dt> + <dd>편집자 검토가 필요하다고 표시된 글들을 교열하고 교정하는 것.</dd> + <dt>어떤 글에서 편집자 검토가 필요합니까?</dt> + <dd>편집자 검토가 필요하다고 표시된 특별한 글들.</dd> + <dt>편집자 검토를 하기 위해서 알아야 하는 것이 있습니까?</dt> + <dd>괜찮은 문법과 맞춤법 실력이 필요합니다. 예를 들어 편집 검토는 문법과 철자에 대한 확인을 해야합니다.</dd> + <dt>편집자 검토는 어떤 단계를 거칩니까?</dt> + <dd> + <ol> + <li>검토할 글을 선택합니다: + <ol> + <li><a href="/ko-KR/docs/needs-review/editorial">편집자 검토가 필요한 글</a> 목록으로 이동합니다. 이곳에는 편집자 검토가 필요한 페이지들이 나열되어 있습니다.</li> + <li>경로가 <code>Template:</code>으로 시작하지 않는 한국어 제목을 가진 페이지를 선택합니다.(<code>Template:</code>페이지는 MDN 매크로코드를 포함하고 있습니다)</li> + <li>글 링크를 클릭해서 페이지를 불러옵니다.</li> + </ol> + </li> + <li><a id="core-steps" name="core-steps"></a>글의 오탈자, 철자, 문법 및 어법상의 오류에 주의를 기울이며 읽습니다. 만일 선택한 글이 능력에 부친다고 생각되면, 다른 글을 새로 선택하십시오.</li> + <li>만일 살펴본 글에 오류가 없다면, 페이지 왼쪽 사이드바에서 "quick review" 상자를 찾아보십시오:<br> + <img alt="Screenshot of Korean version of the editorial review request sidebar box" src="https://mdn.mozillademos.org/files/14677/Screenshot%20of%20the%20editorial%20review%20request%20sidebar%20box_ko.png" style="height: 90px; width: 281px;"></li> + <li><strong>편집 </strong>상자의 선택을 해제하고, <strong>저장 </strong>버튼을 클릭합니다.</li> + <li>오류를 발견했다면, 수정을 해야합니다: + <ol> + <li>페이지 상단의 <strong>편집 </strong>버튼을 클릭합니다. <a href="/ko-KR/docs/Project:MDN/Contributing/Editor_guide">MDN editor</a>가 열립니다.</li> + <li>발견한 오탈자, 문법, 어법상의 오류를 수정 합니다. 모든 오류를 한번에 다 고치지 않아도 괜찮습니다만, 남은 오류가 없다는 확신을 갖기 어렵다면 편집자 검토 요청 상태를 유지해주십시오.</li> + <li>글 하단의 <strong>리비전 답글 </strong>항목을 입력합니다; '<em>편집자 검토: 오타, 문법, 맞춤법 수정됨.</em>'같은 식으로 적으시면 됩니다. 이 리비전 답글의 내용으로 다른 공헌자들이나 사이트 편집자들이 어떤 것이 수정되었는지, 왜 수정했는 지에 대해 알 수 있습니다.</li> + <li><strong>검토가 필요한가요? </strong>에서 <strong>편집 </strong>체크상자를 해제해주십시오. 이 내용은 리비전 답글 항목의 바로 위에 있습니다.</li> + <li><strong>게시 </strong>버튼을 클릭해주세요</li> + </ol> + </li> + </ol> + + <div class="note"> + <p>수정 내용은 저장 직후에 바로 보이지 않을 수 있습니다. 페이지 내용이 처리되고 저장되기 까지는 약간의 시간지연이 있을 수 있습니다.</p> + </div> + </dd> +</dl> diff --git a/files/ko/mdn/contribute/howto/index.html b/files/ko/mdn/contribute/howto/index.html new file mode 100644 index 0000000000..41b5fe582f --- /dev/null +++ b/files/ko/mdn/contribute/howto/index.html @@ -0,0 +1,14 @@ +--- +title: MDN web docs 사용 방법 +slug: MDN/Contribute/Howto +tags: + - 가이드 + - 도움말 + - 시작하기 +translation_of: MDN/Contribute/Howto +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>이 페이지에서는 여러분이 MDN에 공헌하기 위한 목표를 달성하는 데에 도움을 줄 단계별 가이드를 제공합니다.</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ko/mdn/contribute/howto/mdn_계정_생성하기/index.html b/files/ko/mdn/contribute/howto/mdn_계정_생성하기/index.html new file mode 100644 index 0000000000..b3b84a92b1 --- /dev/null +++ b/files/ko/mdn/contribute/howto/mdn_계정_생성하기/index.html @@ -0,0 +1,32 @@ +--- +title: MDN 계정 생성 +slug: MDN/Contribute/Howto/MDN_계정_생성하기 +tags: + - 가입 + - 계정 + - 시작하기 + - 인증 +translation_of: MDN/Contribute/Howto/Create_an_MDN_account +--- +<div>{{MDNSidebar}}</div><p>페이지를 수정하거나 데모에 기여하는 등 MDN의 컨텐츠를 변경하려면 MDN 프로필이 필요합니다. 단지 내용을 읽거나 검색하는 것에는 프로필이 필요없으니 걱정하지 마세요. 아래는 MDN 프로필을 설정하기 위한 가이드입니다.</p> + +<p>MDN에 기여하기로 마음 먹었다면 여러분이 할 일은 다음과 같습니다. :</p> + +<ol> + <li>모든 MDN 페이지의 최상단에는 "Sign in with"(또는 '로그인') 버튼이 있습니다. 마우스를 포인터를 올려 놓으면(모바일 디바이스에서는 탭) MDN에서 사용 가능한 인증 서비스 목록이 나타납니다.</li> + <li>로그인 할 서비스를 선택하세요. Persona 가 아닌 인증 서비스를 선택했다면 여러분의 공개 프로필에 여러분이 어떤 인증 방법으로 인증했는지 표시됩니다.</li> + <li>각 서비스별 인증 단계를 따르십시오.</li> + <li>각 서비스별 인증 단계를 마치고 MDN 페이지로 돌아오면, 이름과 이메일 주소를 입력해야 합니다. <strong>입력한 이름은 모든 작업물에 공개적으로 표시되므로, 메일 주소를 이름으로 사용하지 마십시오.</strong></li> + <li>'MDN 프로필 생성' 버튼을 클릭합니다.</li> + <li>4단계에서 입력한 이메일 주소가 여러분이 인증한 서비스 프로필 상의 이메일 주소와 다르면, 입력한 이메일 주소가 올바른지 확인하게 됩니다. 입력한 이메일 주소로 발송된 확인 메일의 링크를 클릭하세요.</li> +</ol> + +<p>이게 전부입니다! 이제 여러분의 MDN 계정이 생겼으니, 지금 당장 페이지들을 수정하거나 태그를 달 수 있습니다.</p> + +<p>모든 MDN 페이지의 최상단에 있는 여러분의 이름을 클릭하면 여러분의 공개 프로필을 볼 수 있으며, "편집" 버튼을 눌러 새로운 정보를 업데이트 할 수 있습니다. 여러분의 관심사나 블로그 주소, 트위터 계정, 혹은 그 외의 어떤 것이라도 나누어 보세요.</p> + +<div class="note"> +<p><strong>참고:</strong> 새로운 사용자 이름에 공백이나 '@' 문자를 포함할 수 없습니다. 사용자 이름은 당신의 모든 작업물에서 공개적으로 보여진다는 것을 기억하세요!</p> +</div> + +<p> </p> diff --git a/files/ko/mdn/contribute/howto/report_a_problem/index.html b/files/ko/mdn/contribute/howto/report_a_problem/index.html new file mode 100644 index 0000000000..286b4b6ff6 --- /dev/null +++ b/files/ko/mdn/contribute/howto/report_a_problem/index.html @@ -0,0 +1,20 @@ +--- +title: MDN에 문제 보고하기 +slug: MDN/Contribute/Howto/Report_a_problem +translation_of: MDN/Contribute/Howto/Report_a_problem +--- +<div>{{MDNSidebar}}</div> + +<p>가끔씩은 MDN을 이용하면서 몇몇 문제를 발견하게 될 수도 있습니다. 사이트의 내부 구조에서 생긴 문제나 문서 내용에 잘못된 점이 있다면, 직접 수정하거나 문제점을 보고할 수 있습니다. 물론 직접 수정해주는 것이 제일 좋겠지만, 문제점을 알려주는 것이 최선이라면 그것도 괜찮습니다.</p> + +<h3 id="문서의_오류">문서의 오류</h3> + +<p>너무나 당연한 소리이지만, MDN은 위키이기 때문에 여러분들이 할 수 있는 가장 좋은 방법은 직접 수정해주는 것입니다. 하지만 어떻게 해야 할지 잘 모르겠거나 정말로 위급한 상황 하에 있을 경우에는, 다른 사람이 나중에 볼 수 있도록 문제점을 어딘가에 적어두고 싶을 수도 있습니다.</p> + +<p>Mozilla의 모든 경우와 마찬가지로, <a href="https://bugzilla.mozilla.org/form.doc">문서 요청 버그</a>를 제출하여 문서의 문제점을 보고할 수 있습니다. 별로 복잡하지 않은 이 문서 요청 양식을 제출하면 우리가 문제를 해결할 수 있는 자료를 수집할 것입니다.</p> + +<p>물론, 우리들의 쓰기 커뮤니티는 굉장히 바쁘기 때문에, 때로는 문제를 직접 수정하는 것이 가장 빨리 해결하는 방법입니다. 자세한 내용은 <a href="/en-US/docs/MDN/Contribute/Creating_and_editing_pages" title="/en-US/docs/Project:MDN/Contributing/Creating_and_editing_pages">페이지를 만들고 수정하기</a>를 참고하세요.</p> + +<h3 id="사이트_버그_신고나_기능_제안">사이트 버그 신고나 기능 제안</h3> + +<p>MDN 웹사이트에 사용하기 위해 Mozilla가 개발한 플랫폼 <a href="/en-US/docs/Project:MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a>는 지금도 계속해서 개발이 진행중입니다. 수많은 자원 봉사 기여자들을 포함한 우리 개발자들은 이를 끊임없이 개선하고 있습니다. 버그나 사이트의 문제점을 발견하였다면, 아니면 소프트웨어를 더 멋지게 만드는 방법을 제안하고 싶다면 <a href="https://github.com/mdn/kuma/issues/new">Kuma 버그 양식</a>으로 보고할 수 있습니다.</p> diff --git a/files/ko/mdn/contribute/howto/set_the_summary_for_a_page/index.html b/files/ko/mdn/contribute/howto/set_the_summary_for_a_page/index.html new file mode 100644 index 0000000000..e26a3d3a05 --- /dev/null +++ b/files/ko/mdn/contribute/howto/set_the_summary_for_a_page/index.html @@ -0,0 +1,53 @@ +--- +title: 페이지에 대한 요약을 설정하는 방법 +slug: MDN/Contribute/Howto/Set_the_summary_for_a_page +translation_of: MDN/Contribute/Howto/Set_the_summary_for_a_page +--- +<div>{{MDNSidebar}}</div> + +<p>MDN의 페이지에 대한 요약을 정의할 수 있습니다. 이 요약은 검색 엔진의 결과, 시사적인 랜딩 페이지와 같은 다른 MDN 페이지 또는 툴팁에서 다양하게 사용됩니다. 요약은 페이지 내용의 나머지가 없이도 페이지의 문맥과 다른 문맥에서 보여졌을 때 모두 의미가 통해야 합니다.</p> + +<p>요약은 한 페이지 이내로 분명하게 정의됩니다. 요약이 분명하게 정의되지 않았다면, 보통 첫 번째 문장 정도가 사용되는데 이는 언제나 목적을 위한 최고의 텍스트가 아닙니다.</p> + +<table class="full-width-table"> + <tbody> + <tr> + <td><strong>어떤 일을 해야 하나요?</strong></td> + <td>다른 문맥에서 요약으로 사용되어야 하는 페이지 내의 텍스트를 표시하기; 필요하다면 이 작업은 적합한 텍스트를 작성하는 것을 포함할 수 있습니다.</td> + </tr> + <tr> + <td><strong>어디서 이 일이 필요하나요?</strong></td> + <td>요약이 부족하거나 미흡한 페이지.</td> + </tr> + <tr> + <td><strong>이 일을 하기 위해 무엇을 알아야 하나요?</strong></td> + <td>MDN 에디터 사용 능력; 좋은 영작문 솜씨; 좋은 요약을 작성하기 위한 주제에 대한 충분한 친숙도</td> + </tr> + <tr> + <td><strong>이 일을 하기 위한 단계는 어떻게 되나요?</strong></td> + <td> + <ol> + <li>요약을 설정할 페이지를 고릅니다: + <ol> + <li><a href="/en-US/docs/MDN/Doc_status">MDN documentation status</a> 페이지에서, <strong>Sections </strong>아래에서 알고 있는 주제의 링크를 클릭합니다.(예를 들어, HTML).</li> + <li>주제의 문서 상태 페이지에서 <strong>Summary </strong>테이블의 <strong>Pages </strong>헤더를 클릭합니다. 해당 주제 섹션의 모든 페이지 인덱스로 이동됩니다.; 왼쪽 열에는 페이지 링크들이, 오른쪽 열에는 태그와 요약들이 보입니다.</li> + <li>요약이 없거나, 좋지 않은 요약을 가진 페이지를 고릅니다.</li> + <li>링크를 클릭하여 해당 페이지로 갑니다.</li> + </ol> + </li> + <li><strong>Edit</strong>를 클릭하여서 MDN 에디터로 페이지를 엽니다.</li> + <li>문맥과 상관없이 요약으로 사용될 한 문장 또는 두 문장을 찾습니다. 필요하다면, 기존의 내용을 수정하여서 문장이 좋은 요약이 되도록 만들거나 수정합니다.</li> + <li>요약으로 사용될 텍스트를 선택합니다.</li> + <li>에디터 툴바의 <em>Styles</em> 위젯에서 <strong>SEO Summary</strong>를 선택합니다. (이것은 페이지 소스에서 선택된 텍스트에 class="seoSummary"를 가진 {{HTMLElement("span")}} 엘레멘트를 추가합니다. )</li> + <li>"페이지 요약 설정"과 같은 수정 코멘트와 함께 변경사항을 저장합니다.</li> + </ol> + </td> + </tr> + </tbody> +</table> + +<p> </p> + +<p> </p> + +<p> </p> diff --git a/files/ko/mdn/contribute/howto/tag/index.html b/files/ko/mdn/contribute/howto/tag/index.html new file mode 100644 index 0000000000..a0604dc8fa --- /dev/null +++ b/files/ko/mdn/contribute/howto/tag/index.html @@ -0,0 +1,396 @@ +--- +title: 페이지에 올바르게 태그하는 방법 +slug: MDN/Contribute/Howto/Tag +tags: + - Beginner + - Contribute + - Glossary + - Guide + - Howto + - Intro + - MDN Meta + - Tutorial +translation_of: MDN/Contribute/Howto/Tag +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><strong>문서 태그</strong>는 방문자에게 유용한 컨텐츠를 제공하는 중요한 방법입니다. 각 페이지는 콘텐츠 정리에 도움을 줄 수 있도록 몇 개의 태그를 가져야 합니다. <span class="seoSummary">본 페이지는 독자들이 정보를 찾을 때나, 사이트를 체계적으로 유지할 때 필요한 페이지 태그를 하는 가장 좋은 방법을 설명합니다.</span></p> + +<p>태그를 편집할 때 사용하는 인터페이스에 대한 도움이 필요하시면, 편집 가이드의 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#The_tags_box">태그 섹션</a>을 참고하세요.</p> + +<p>아래의 설명처럼 태그를 적절히 사용해주세요. 그렇지 않으면, 저희의 자동화 도구가 콘텐츠 목록, 랜딩 페이지, 문서 간 링크 등을 정확하게 생성하지 못합니다.</p> + +<h2 id="MDN이_태그를_사용하는_방법">MDN이 태그를 사용하는 방법</h2> + +<p>MDN은 태그를 여러가지 방법으로 사용합니다.</p> + +<dl> + <dt>문서 분류</dt> + <dd>어떤 종류의 문서인가요? 레퍼런스? 튜토리얼? 랜딩 페이지? 저희 방문자는 태그를 사용해 검색 결과를 필터링 할 수 있으므로 매우 중요합니다.</dd> + <dt>항목 식별</dt> + <dd>무엇에 관한 문서인가요? API? DOM? 그래픽? 다시 말씀드리지만, 태그를 사용해 검색 겨로가를 필터링 할 수 있으므로 중요합니다.</dd> + <dt>API 식별</dt> + <dd>API 레퍼런스 페이지는 문서화된 API의 특정 구성요소를 식별할 수 있어야 합니다. (즉, 어떤 인터페이스인지, 그리고 해당되는 경우에 페이지가 다루는 속성이나 방법).</dd> + <dt>기술 현황</dt> + <dd>이 기술의 상태는 어떤가요? 비표준인가요? 더 이상 사용되지 않나요? 실험 단계인가요?</dd> + <dt>기술 수준</dt> + <dd>튜토리얼이나 가이드의 경우, 이 글이 다루는 내용이 얼마나 어려운가요?</dd> + <dt>문서 메타데이터</dt> + <dd>기여자 커뮤니티는 태그를 사용하여 어떤 페이지에 어떤 작업이 필요한지 추적합니다.</dd> +</dl> + +<h2 id="태그_유형별_가이드">태그 유형별 가이드</h2> + +<p>다음은 태그 유형 및 적합한 값에 대한 빠른 가이드입니다.</p> + +<h3 id="문서_카테고리">문서 카테고리</h3> + +<p>여기에 있는 카테고리들로 글을 태그하면, 자동화 시스템이 방문 페이지, 목차 등을 좀 더 정확하게 생성할 수 있습니다. 저희의 새로운 검색 시스템은 이런 용어들을 사용해서 방문자들이 레퍼런스나 가이드 정보를 찾을 수 있을 겁니다.</p> + +<p>다음과 같은 카테고리 명을 표준 태그로 사용하고 있습니다.</p> + +<dl> + <dt><code>{{Tag("Intro")}}</code></dt> + <dd> + <p>이 문서는 주제에 관한 입문 자료를 제공합니다. 이상적으로는 각 기술 영역에 하나의 인트로만 존재해야 합니다.</p> + </dd> + <dt><code>{{Tag("Reference")}}</code></dt> + <dd>이 문서는 API, 요소(Element), 속성 등에 관한 참조 자료가 포함되어 있습니다.</dd> + <dt><code>{{Tag("Landing")}}</code></dt> + <dd>이 문서는 랜딩 페이지입니다.</dd> + <dt><code>{{Tag("Guide")}}</code></dt> + <dd>이 문서는 방법 일람이나 가이드입니다.</dd> + <dt><code>{{Tag("Example")}}</code></dt> + <dd>이 문서는 코드 샘플 페이지거나, 코드 샘플(한 줄짜리 구문 예제가 아닌 실제로 유용한 코드 조각)을 포함하고 있습니다.</dd> +</dl> + +<h3 id="주제">주제</h3> + +<p>주제의 범위를 밝힘으로써 검색 결과를 개선하는데 도움을 주실 수 있습니다(또한 랜딩 페이지와 네비게이션에도 도움을 줍니다).</p> + +<p>새로운 항목이 생길 수 있어 유연성을 위한 여지가 있긴 하지만, 되도록 API나 기술의 이름으로 제한하려고 합니다. 자주 쓰이는 예시입니다.</p> + +<ul> + <li><code>{{Tag("HTML")}}</code></li> + <li><code>{{Tag("CSS")}}</code></li> + <li><code>{{Tag("JavaScript")}}</code> (대문자 S)</li> + <li><code>{{Tag("Document")}}</code></li> + <li><code>{{Tag("DOM")}}</code></li> + <li><code>{{Tag("API")}}</code> API의 각 개요, 인터페이브, 메서드, 속성마다.</li> + <li><code>{{Tag("Method")}}</code> API의 각 메서드마다.</li> + <li><code>{{Tag("Property")}}</code> API의 각 속성마다.</li> + <li><code>{{Tag("Graphics")}}</code></li> + <li><code>{{Tag("SVG")}}</code></li> + <li><code>{{Tag("WebGL")}}</code></li> + <li><code>{{Tag("Tools")}}</code></li> + <li><code>{{Tag("Web")}}</code></li> + <li><code>{{Tag("Element")}}</code></li> +</ul> + +<p>대체로, your topic identification tag should be the name of an interface with a number of related pages (like <a href="/en-US/docs/Web/API/Node" title="/en-US/docs/Web/API/Node">Node</a>, which has many pages for its various properties and methods), or the name of an overall technology type. You might tag a page about WebGL with <code>Graphics</code> and <code>WebGL</code>, for example, but a page about {{HTMLElement("canvas")}} with <code>HTML</code>, <code>Element</code>, <code>Canvas</code>, and <code>Graphics</code>.</p> + +<h4 id="모질라_관련_콘텐츠">모질라 관련 콘텐츠</h4> + +<p>아래 태그는 모질라 관련 콘텐츠에만 사용합니다.</p> + +<ul> + <li><code>{{Tag("Mozilla")}}</code></li> + <li><code>{{Tag("Firefox")}}</code></li> + <li><code>{{Tag("Firefox OS")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> +</ul> + +<h3 id="API_식별">API 식별</h3> + +<p>API 참조 내에서 각 문서는 API에서 다루는 부분을 식별해야합니다.</p> + +<dl> + <dt>{{tag("Interface")}}</dt> + <dd>The main article for an interface should have this tag. For example, {{domxref("RTCPeerConnection")}}.</dd> + <dt>{{tag("Constructor")}}</dt> + <dd>Each interface may have up to one page tagged "Constructor"; this is the interface's constructor. The page should have the same name as the interface, like {{domxref("RTCPeerConnection.RTCPeerConnection()")}}.</dd> + <dt>{{tag("Property")}}</dt> + <dd>Every article describing a particular property within an interface needs this tag. See {{domxref("RTCPeerConnection.connectionState")}}, for example.</dd> + <dt>{{tag("Method")}}</dt> + <dd>Each article documenting an interface method needs this tag. See {{domxref("RTCPeerConnection.createOffer()")}} for example.</dd> +</dl> + +<p>In addition, the reference pages need to include interface, property, and method names among their tags. Some examples:</p> + +<dl> + <dt>The interface {{domxref("RTCPeerConnection")}}</dt> + <dd>Include the tag "RTCPeerConnection" along with the other relevant tags ("Interface", "WebRTC", "WebRTC API", "API", "Reference", and so forth).</dd> + <dt>The method {{domxref("RTCPeerConnection.createOffer()")}}</dt> + <dd>Include the tags "RTCPeerConnection" and "createOffer" (note <em>no</em> parentheses in tag names!) along with the other relevant tags, including "WebRTC", "WebRTC API", "API", "Reference", and so forth. Consider including things like "Offer" and "SDP", which are also relevant here.</dd> + <dt>The property {{domxref("RTCPeerConnection.iceConnectionState")}}</dt> + <dd>Include the tags "RTCPeerConnection" and "iceConnectionState" along with the other relevant tags, including "WebRTC", "WebRTC API", "API" and "Reference". Also consider including "ICE".</dd> +</dl> + +<h3 id="기술_상태">기술 상태</h3> + +<p>To help the reader understand how viable a technology is, we use tags to label pages as to the status of the technology's specification. This isn't as detailed as actually explaining what the spec is and how far the technology has come in the specification process (that's what the Specifications table is for), but it helps the reader judge, at a glance, whether it's a good idea to use the technology described in the article.</p> + +<p>다음 태그와 가능한 값은 다음과 같습니다:</p> + +<dl> + <dt><code>{{Tag("Read-only")}}</code></dt> + <dd>Apply this tag to reference pages which describe a property or attribute which is read-only.</dd> + <dt><code>{{Tag("Non-standard")}}</code></dt> + <dd>Indicates that the technology or API described on the page is not part of a standard, whether it's stable or not in any browsers which implement it (if it's not stable, it should also be {{Tag("Experimental")}}). If you don't use this tag, your readers will assume the technology is standard. The compatibility table on the page should clarify which browser(s) support this technology or API.</dd> + <dt><code>{{Tag("Deprecated")}}</code></dt> + <dd>The technology or API covered on the page is marked as deprecated in the specification, and is likely to eventually be removed, but is generally still available in current versions of browsers.</dd> + <dt><code>{{Tag("Obsolete")}}</code></dt> + <dd>The technology or API has been deemed obsolete and has been removed (or is actively being removed) from all or most current browsers.</dd> + <dt><code>{{Tag("Experimental")}}</code></dt> + <dd>The technology is not standardized, and is an experimental technology or API that may or may not ever become part of a standard. It is also subject to change in the browser engine (typically only one) that implements it. If the technology isn't part of any specification (even in draft form), it should also have the {{tag("Non-standard")}} tag.</dd> + <dt><code>{{Tag("Needs Privileges")}}</code></dt> + <dd>The API requires privileged access to the device on which the code is running.</dd> + <dt><code>{{Tag("Certified Only")}}</code></dt> + <dd>The API only works in certified code.</dd> +</dl> + +<p>These tags are no excuse to leave out the <a href="/en-US/docs/Project:Compatibility_tables" title="/en-US/docs/Project:Compatibility_tables">compatibility table</a> in your article! That should always be present.</p> + +<h3 id="기술_수준">기술 수준</h3> + +<p>Use the skill-level tag type only for guides and tutorials (that is, pages tagged <code>Guide</code>) to help users choose tutorials based on how familiar they are with a technology. There are three values for this:</p> + +<dl> + <dt><code>{{Tag("Beginner")}}</code></dt> + <dd>Articles designed to introduce the reader to a technology they've never used or have only a passing familiarity with.</dd> + <dt><code>{{Tag("Intermediate")}}</code></dt> + <dd>Articles for users who have gotten started with the technology but aren't experts.</dd> + <dt><code>{{Tag("Advanced")}}</code></dt> + <dd>Articles about stretching the capabilities of a technology and of the reader.</dd> +</dl> + +<h3 id="문서_메타데이터">문서 메타데이터</h3> + +<p>글쓰기 커뮤니티는 태그를 사용하여 문서에 특정 유형의 작업이 필요하다고 표시합니다. 우리가 가장 많이 사용하는 목록은 다음과 같습니다:</p> + +<dl> + <dt><code>{{Tag("Draft")}}</code></dt> + <dd>The article is not complete, and is at least in theory still actively being updated (although it's also possible it's been forgotten about). Try to check with the most recent contributors before making changes, in order to avoid potential content collisions.</dd> + <dt><code>{{Tag("NeedsContent")}}</code></dt> + <dd>The article is a stub, or is otherwise lacking information. This tag means that someone should review the content and add more details and/or finish writing the article.</dd> + <dt><code>{{Tag("NeedsExample")}}</code></dt> + <dd>The article needs one or more examples created to help illustrate the article's point. These examples should use the <a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">live sample system</a>.</dd> + <dt><code>{{Tag("NeedsLiveSamples")}}</code></dt> + <dd>The article has one or more examples that need to be updated to use the <a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">live sample system</a>.</dd> + <dt><code>{{Tag("NeedsUpdate")}}</code></dt> + <dd>The content is out of date and needs to be updated.</dd> + <dt><code>{{Tag("l10n:exclude")}}</code></dt> + <dd>The content is not really worth localizing and will not appear on localization status pages.</dd> + <dt><code>{{Tag("l10n:priority")}}</code></dt> + <dd>The content is important and should be marked as a priority for MDN translators. Shows up in an extra priority table on localization status pages.</dd> +</dl> + +<h2 id="조합하기">조합하기</h2> + +<p>각 페이지에 여러 유형의 태그를 할당할 수 있습니다.</p> + +<dl> + <dt>초보자를 위한 WebGL 튜토리얼</dt> + <dd><code>WebGL</code>, <code>Graphics</code>, <code>Guide</code>, <code>Beginner</code></dd> + <dt>{{HTMLElement("canvas")}}용 레퍼런스 페이지</dt> + <dd><code>Canvas</code>, <code>HTML</code>, <code>Element</code>, <code>Graphics,</code> <code>Reference</code></dd> + <dt>Firefox OS 개발자 도구용 랜딩 페이지</dt> + <dd><code>Tools</code>, <code>Firefox OS</code>, <code>Landing</code></dd> +</dl> + +<h2 id="태그_추가_및_검색_필터">태그 추가 및 검색 필터</h2> + +<p>MDN 페이지에 올바르게 태그를 지정하지 않으면 검색 필터가 제대로 작동하지 않습니다. 다음은 검색 필터 목록과 검색 태그입니다.</p> + +<div class="note"> +<p><strong>참고:</strong> If multiple tags are listed under "Tag name," that means any one or more of these tags must be present for the article to match.</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">필터<br> + 그룹</th> + <th scope="col">검색명</th> + <th scope="col">태그명</th> + </tr> + </thead> + <tbody> + <tr> + <th>주제</th> + <td>Open Web Apps</td> + <td>{{Tag("Apps")}}</td> + </tr> + <tr> + <th> </th> + <td>HTML</td> + <td>{{Tag("HTML")}}</td> + </tr> + <tr> + <th> </th> + <td>CSS</td> + <td>{{Tag("CSS")}}</td> + </tr> + <tr> + <th> </th> + <td>JavaScript</td> + <td>{{Tag("JavaScript")}}</td> + </tr> + <tr> + <th> </th> + <td>APIs and DOM</td> + <td>{{Tag("API")}}</td> + </tr> + <tr> + <th> </th> + <td>Canvas</td> + <td>{{Tag("Canvas")}}</td> + </tr> + <tr> + <th> </th> + <td>SVG</td> + <td>{{Tag("SVG")}}</td> + </tr> + <tr> + <th> </th> + <td>MathML</td> + <td>{{Tag("MathML")}}</td> + </tr> + <tr> + <th> </th> + <td>WebGL</td> + <td>{{Tag("WebGL")}}</td> + </tr> + <tr> + <th> </th> + <td>XUL</td> + <td>{{Tag("XUL")}}</td> + </tr> + <tr> + <th> </th> + <td>Marketplace</td> + <td>{{Tag("Marketplace")}}</td> + </tr> + <tr> + <th> </th> + <td>Firefox</td> + <td>{{Tag("Firefox")}}</td> + </tr> + <tr> + <th> </th> + <td>안드로이드 용 Firefox</td> + <td>{{Tag("Firefox Mobile")}}</td> + </tr> + <tr> + <th> </th> + <td>데스크탑 용Firefox</td> + <td>{{Tag("Firefox Desktop")}}</td> + </tr> + <tr> + <th> </th> + <td>Firefox 운영체제</td> + <td>{{Tag("Firefox OS")}}</td> + </tr> + <tr> + <th> </th> + <td>모바일</td> + <td>{{Tag("Mobile")}}</td> + </tr> + <tr> + <th> </th> + <td>웹 개발</td> + <td>{{Tag("Web Development")}}</td> + </tr> + <tr> + <th> </th> + <td> + <p>애드온 &<br> + 확장프로그램</p> + </td> + <td>{{Tag("Add-ons ")}}|| {{Tag("Extensions")}} || {{Tag("Plugins")}} || {{Tag("Themes")}}</td> + </tr> + <tr> + <th> </th> + <td>게임</td> + <td>{{Tag("Games")}}</td> + </tr> + <tr> + <th>기술<br> + 수준</th> + <td>전문가</td> + <td>{{Tag("Advanced")}}</td> + </tr> + <tr> + <th> </th> + <td>중급자</td> + <td>{{Tag("Intermediate")}}</td> + </tr> + <tr> + <th> </th> + <td>초급자</td> + <td>{{Tag("Beginner")}}</td> + </tr> + <tr> + <th> + <p>문서 <br> + 형식</p> + </th> + <td>문서</td> + <td><em>This restricts the search to docs content, leaving out Hacks and other MDN content.</em></td> + </tr> + <tr> + <th> </th> + <td>체험판</td> + <td><em>This includes Demo Studio content in the search results.</em></td> + </tr> + <tr> + <th> </th> + <td>도구</td> + <td>{{Tag("Tools")}}</td> + </tr> + <tr> + <th> </th> + <td>코드 샘플</td> + <td>{{Tag("Example")}}</td> + </tr> + <tr> + <th> </th> + <td>튜토리얼</td> + <td>{{Tag("Guide")}}</td> + </tr> + <tr> + <th> </th> + <td>개발자<br> + 프로필</td> + <td><em>This includes developer profiles from the MDN site in the search results.</em></td> + </tr> + <tr> + <th> </th> + <td>외부<br> + 리소스</td> + <td><em>The dev team is still figuring this out...</em></td> + </tr> + </tbody> +</table> + +<h2 id="해결할_수_있는_태그_추가_문제">해결할 수 있는 태그 추가 문제</h2> + +<p>해결할 수 있는 여러 종류의 태그 추가 문제가 있습니다:</p> + +<dl> + <dt>태그 없음</dt> + <dd>Generally articles should have at <em>least</em> a "{{anch("Document category", "category")}}" tag and a "{{anch("Topic", "topic")}}" tag. Usually other tags are appropriate as well, but if you can help us ensure that the minimum tags are present, you'll be a documentation hero!</dd> + <dt>표준을 따르지 않은 태그</dt> + <dd>Please fix any documents whose tags don't follow the standards on this page.<br> + Note that you may occasionally see some localized tags (such as <code>Référence</code>) showing up on some English pages. This was due to a <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048">bug in Kuma</a>, which caused the tags to reappear even if they were deleted. That bug has <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048#c37">since been fixed</a>, so any remaining localized tags can be cleaned up if they're spotted.</dd> + <dt>올바르지 않은 태그</dt> + <dd>If you're looking at an article about HTML and it's tagged "JavaScript", that's probably wrong! Likewise, if an article discusses Mozilla internals but has a "Web" tag, that's probably wrong too. Remove these tags and add the right tags if they aren't already there. Please also correct misspelled tags (e.g., "Javascript" will still match, since tags are case-insensitive, but let's not be sloppy!).</dd> + <dt>누락된 태그</dt> + <dd>If an article has some but not all of the tags it needs, feel free to add more. For example, if a page in JavaScript reference is (correctly) tagged "JavaScript" but nothing else, you're invited to tag the page "Reference" as well!</dd> + <dt>스팸 태그</dt> + <dd>This insidious beast is the most revolting tag problem of all: some Web vermin has deposited its droppings in the page tags (like "Free warez!" or "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time"). We've got to delete these right away! They're ugly, they're hard to manage if they're allowed to linger too long, and they're terrible for {{Glossary("SEO")}}.</dd> +</dl> + +<p>If you see one (or more) of these problems, please <a href="/en-US/docs/Project:MDN/Contributing/Getting_started#Logging_into_MDN">log into MDN</a> and click EDIT at the top right of the MDN window. Once the editor loads up, scroll down to the bottom of the page, where you'll see the tag box. For more details on the tagging interface, see "<a href="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box" title="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box">The tags box</a>" in the <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide" title="/en-US/docs/Project:MDN/Contributing/Editor_guide">MDN editor guide</a>.</p> diff --git a/files/ko/mdn/contribute/howto/tag_javascript_pages/index.html b/files/ko/mdn/contribute/howto/tag_javascript_pages/index.html new file mode 100644 index 0000000000..8825a20a62 --- /dev/null +++ b/files/ko/mdn/contribute/howto/tag_javascript_pages/index.html @@ -0,0 +1,69 @@ +--- +title: JavaScript tag를 다는 방법 +slug: MDN/Contribute/Howto/Tag_JavaScript_pages +translation_of: MDN/Contribute/Howto/Tag_JavaScript_pages +--- +<div>{{MDNSidebar}}</div><p class="summary">태그달기는 페이지에 메타 정보를 추가함을 통해 관련된 내용이 묶여질수 있도록 하는 작업을 포함합니다.</p> + +<dl> + <dt><strong>어디서 필요한가요?</strong></dt> + <dd><a href="/en-US/docs/Web/JavaScript/Doc_status#No_tags">태그가 없는 JavaScript에 관련된 특정한 페이지</a>안에서 필요합니다.</dd> + <dt><strong>작업을 위해서 무엇을 알 필요가 있나요?</strong></dt> + <dd>메소드나 변수들과 같은 기본적 JavaScript 코딩 지식이 필요합니다.</dd> + <dt>어떤 절차가 있나요?</dt> + <dd> + <ol> + <li>위에 링크된 페이지들중 하나를 선택하세요</li> + <li>페이지를 로드하기위해 기사링크를 클릭하세요</li> + <li>페이지가 로드됐다면, 맨 위 있는EDIT버튼을 클릭하세요; 이는 당신을 MDN 에디터로 만들어줍니다.</li> + <li>적어도 JavaScript 태그가 추가돼야 합니다. 아래에는 가능한 다른 태그들입니다. + <table class="standard-table"> + <thead> + <tr> + <th scope="col">Tag</th> + <th scope="col">What pages to use it on</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>Method</code></td> + <td>methods</td> + </tr> + <tr> + <td><code>Property</code></td> + <td>properties</td> + </tr> + <tr> + <td><code>prototype</code></td> + <td>prototypes</td> + </tr> + <tr> + <td>Object type name</td> + <td>methods of an object; for example String.fromCharCode should have the tag <code>String</code></td> + </tr> + <tr> + <td><code>ECMAScript6 </code>and <code>Experimental</code></td> + <td>features added in a new ECMAScript version</td> + </tr> + <tr> + <td><code>Deprecated</code></td> + <td>deprecated features (whose use is discouraged but still supported)</td> + </tr> + <tr> + <td><code>Obsolete</code></td> + <td>obsolete features (which are no longer supported in modern browsers)</td> + </tr> + <tr> + <td>others</td> + <td>See <a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards">MDN tagging standards</a> for other possible tags to apply</td> + </tr> + </tbody> + </table> + </li> + <li>Save with a comment.</li> + <li>You're done!</li> + </ol> + </dd> +</dl> + +<p> </p> diff --git a/files/ko/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html b/files/ko/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html new file mode 100644 index 0000000000..1eddcc7383 --- /dev/null +++ b/files/ko/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html @@ -0,0 +1,108 @@ +--- +title: 사람들이 웹에 대해 알 수 있도록 기사를 작성하는 방법 +slug: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +translation_of: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +--- +<div>{{MDNSidebar}}</div> + +<p>MDN의 학습 영역(<strong><a href="/en-US/docs/Learn">Learning Area</a>)은</strong> 새로운 개발자들에게 웹 개념을 소개하는 글들을 위한 우리의 집입니다. 왜냐하면 학습 영역의 콘텐츠는 대부분 초보자를 위한 것들이고, 당신의 지식을 공유하고 웹에 대해서 알고 싶은 사람들을 돕는 좋은 공간이기 때문입니다. 새로운 개발자들이 이 콘텐츠를 따라 할 수 있도록 하는 것이 중요합니다. 따라서 우리는 특별히 관심을 기울여야 합니다. </p> + +<p><span class="seoSummary">이 글에서는 학습 영역(<a href="/en-US/docs/Learn">Learning Area</a>)을 위한 페이지를 작성하는 방법을 설명합니다.</span></p> + +<h2 id="학습_영역_기사를_작성하는_방법">학습 영역 기사를 작성하는 방법</h2> + +<p>당신의 지식을 공유하려면 아래의 큰 초록색 버튼을 누르세요. 그러면 다섯 단계로 이어집니다. 만약 당신이 아이디어를 찾는다면, 우리의 트렐로 보드(<a href="https://trello.com/b/LDggrYSV">our team Trello board</a>)를 살펴보세요.</p> + +<p></p><div class="align-center"><a class="button ignore-external mega positive" href="/ko/docs/new?parent=111819">새 학습 기사 작성<div></div></a></div><p></p> + +<p>이 기사는 정확한 위치에 도달할 수 없을지도 모르지만, 최소한 그것은 MDN에게 달려 있습니다. 만약 당신이 정확한 위치로 옮기고 싶다면 우리(<a href="/en-US/docs/Learn#Contact_us">Contact us</a>)에게 연락해 주세요.</p> + +<h3 id="1단계_두개의_요약문_작성">1단계 : 두개의 요약문 작성</h3> + +<p>기사의 첫 문장은 당신이 다루고자 하는 주제를 요약해야 하고, 두번째 문장은 당신이 기사에 실린 물건들을 좀 더 구체적으로 다루어야 합니다. 예를 들어 :</p> + +<div class="summary"> +<p>{{glossary("HTML")}} HTML파일에는 정형 콘텐츠, {{Glossary("CSS")}}, 또 다른 주요 웹 기술이 포함되어 있어 콘텐츠를 원하는 대로 바라볼 수 있습니다. 이 기사에서는 이 기술이 어떻게 작동하는지, 어떻게 기본적인 예제를 작성하는지 살펴보겠습니다. </p> +</div> + +<p>예를 들어 CSS가 페이지 스타일에 사용되는 핵심 웹 기술이라고 간단히 설명해 주세요. 그것은 독자들이 기사의 주제가 무엇인지에 대한 꽤 좋은 아이디어를 얻을 수 있는 충분한 근거가 됩니다. </p> + +<p>왜냐하면 학습 영역 기사들은 주로 초보자를 대상으로 하고, 각각의 기사는 너무 많은 새로운 정보로 독자들을 압도하지 않도록 한가지 간단한 주제를 다루어야 하기 때문입니다. 만약 당신이 기사를 한 문장으로 요악하지 못하면, 너무 많은 것을 하나의 기사에서 다뤄야 할 지도 모릅니다.</p> + +<h3 id="2단계_상단_상자_추가">2단계 : 상단 상자 추가</h3> + +<p>그리곤 독자들의 학습 과정에서 어떤 영향이 있는지 파악하는 것을 돕기 위해서 상단 상자를 추가합니다. 하단에 하나의 예로"URL과 그 구조의 이해(<a href="/en-US/docs/Learn/Understanding_URLs">Understanding URLs and their structure</a>)"에 대한 상단 상자가 있습니다. 당신의 기사를 쓰는 데 이 기사를 참고할 수 있습니다.</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">필수 조건:</th> + <td>먼저 인터넷이 어떻게 작동하는지(<a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/How_the_Internet_works">how the Internet works</a>), 웹서버가 무엇인지(<a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/What_is_a_Web_server">what a Web server is</a>), 웹에서 링크의 개념(<a class="new" href="https://developer.mozilla.org/en-US/docs/Learn/Understanding_links_on_the_web">the concepts behind links on the web</a>)을 알아야 합니다.</td> + </tr> + <tr> + <th scope="row">목표:</th> + <td>URL에 대해서와 URL이 어떻게 웹에서 작동하는지를 배웁니다.</td> + </tr> + </tbody> +</table> + +<dl> + <dt>필수 조건</dt> + <dd>독자가 이 기사를 이해하기 위해 반드시 알고 있어야 할 것이 무엇인가요? 가능한 한 각 필수 요소에 대한 링크를 해당 개념을 다루는 다른 학습 영역 문서에 연결하세요. (사전 지식이 필요 없는 기초적인 기사가 아니라면)</dd> + <dt>목표</dt> + <dd> + <p>이 섹션에서는 독자가 글을 통해 습득할 내용을 간략하게 설명합니다. 이것은 요약문과는 좀 다릅니다, 요약문에서는 기사의 주제를 요약하지만 목표 부분은 독자들이 기사의 과정을 통해 달성할 수 있는 것을 구체적으로 제시합니다.</p> + </dd> +</dl> + +<div class="note"> +<p><strong>Note:</strong> 이 테이블을 생성하려면, 위의 예제 테이블을 복사하여 붙여 넣을 수 있으며, MDN의 editor의 <a href="/en-US/docs/MDN/Contribute/Editor/Tables">table tool</a>을 사용할 수 있습니다. 테이블 도구를 사용하도록 선택한 경우에는 기본 standard-table 클래스 이외에 learn-box CSS 클래스를 추가해야 합니다. 이렇게 하려면 테이블 속성을 생성하거나 편집할 때"Advanced"패널로 이동하여 <strong>스타일시트 클래스</strong> 필드를 "standard-table learn-box"로 설정합니다. </p> +</div> + +<h3 id="3단계_전체_설명_작성">3단계 : 전체 설명 작성</h3> + +<p>다음으로 가장 중요한 개념을 강조하는 기사를 좀 더 자세히 설명하는 더 긴 설명을 작성합니다. 왜 독자들이 이 주제를 배우고 당신의 기사를 읽는 데 시간을 할애해야 하는지 설명하는 것을 잊지 마세요!</p> + +<h3 id="4단계_깊이_들어가기">4단계 : 깊이 들어가기</h3> + +<p>모든 작업을 마친 후, 마침내 주제에 더욱 깊이 들어갈 수 있습니다. 원하는 대로 이 분야의 기사를 작성합니다(우리의 <a href="/en-US/docs/MDN/Contribute/Style_guide">style guide</a>를 자유롭게 참고하셔도 됩니다). 당신이 빛날 수 있는 기회입니다! 작성하는 주제에 대해 자세히 설명합니다. 전체 참조 문서에 대한 링크를 제공하고, 기술이 어떻게 작동하는지 설명하고, 구문 및 사용 상세 내역을 제공하는 방법을 설명합니다. 당신이 하고 싶은 대로 하세요!</p> + +<p>가이드로서, 여기에 초보자들을 위한 몇가지 조언이 있습니다:</p> + +<ul> + <li>하나의 주제에 집중합니다. 만약 다른 주제를 다뤄야 할 필요가 있다고 생각하는 경우, 주제인 기사에서 벗어났거나 둘 이상의 기사를 작성해야 한다는 것을 뜻합니다.</li> + <li>간단한 말로 작성하세요. 가능한 기술 용어를 사용하거나, 해당 용어를 정의하고, 해당 용어의 용어집에 연결할 수 있도록 합니다.</li> + <li>이론적 개념을 쉽게 이해할 수 있도록 간단한 예제를 포함시킨다. 사람들의 최고의 학습법은 예제입니다. 학문적인 논문을 쓰는 대신에, 우리는 초보자들이 원문을 쉽게 따라오기를 원합니다.</li> + <li> + <p>시각적인 보조 장치는 쉽게 소화할 수 있고 추가 정보를 전달하기도 한다. 이미지, 다이어그램, 비디오 및 표를 자유롭게 사용하세요. 텍스트를 포함하는 도표 또는 차트를 사용하는 경우,"SVG"를 사용하여 텍스트를 현지화할 수 있습니다. </p> + </li> +</ul> + +<p>우리 기능의 첫번째 섹션을 살펴보세요. 몇가지 좋은 설명 섹션을 볼 수 있는 코드 문서를 보세요.(<a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions">Functions — reusable blocks of code</a>)</p> + +<h3 id="5단계_능동적_학습_자료_제공">5단계 : "능동적 학습" 자료 제공</h3> + +<p>기사에 삽화를 넣는 것은 독자들이 더 쉽게 이해하고 배우는데 도움이 된다. 완수할 수 있는 연습, 튜토리얼 과제를 제공하세요. 여러분의 기사를 적극적으로 사용하고 실험하고 실험하고 실험하는 것을 통해, 여러분은 그들의 뇌에 정보를 "잠금" 하는 것을 도울 수 있습니다.</p> + +<p>직접 예제(<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">live samples</a>)로 페이지 안에 포함시키거나 직접 예제처럼 제대로 작동하지 않는 경우 링크하는 것(<a href="/en-US/docs/MDN/Contribute/Editor/Links">link to them</a>)을 선택할 수 있습니다. 만약 여러분이 이 가치있는 자료를 만드는데 관심이 있다면, 웹을 배우는 것을 돕기 위한 대화형 연습 만들기(<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">Create an interactive exercise to help learning the Web</a>) 에 대한 기사를 읽어보세요.</p> + +<p>기존의 능동적인 학습 자료에 대한 링크를 제공할 수 없는 경우(관련 자료에 대해서 모르거나 만들 시간이 없을 경우) "NeedsActiveLearning"를 문서에 태그하세요. 다른 기여자들은 능동적인 학습 자료가 필요한 기사를 찾을 수 있고 당신이 그것들을 고안해 낼 수 있도록 도와 줄 지도 모릅니다.</p> + +<p>실시간 상호적인 학습 연습에 대한 <a href="/en-US/docs/Learn/CSS/Introduction_to_CSS/Simple_selectors#Active_learning_Selecting_different_elements">Active learning: selecting different elements</a>를 살펴보거나 <a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions#Active_learning_Playing_with_scope">Active learning: Playing with scope</a>를 통해 로컬에서 탬플릿을 다운로드하고 수정하는 다양한 형태의 연습이 제공한 단계를 따라가세요.</p> + +<h3 id="6단계_문서를_검토하고_탐색_영역_메뉴에_추가하세요">6단계 : 문서를 검토하고 탐색 영역 메뉴에 추가하세요</h3> + +<p>기사를 쓰고 난 후, 우리가 보고 검토하고 개선점을 제안할 수 있도록 알려주세요. 연락할 수 있는 가장 좋은 방법은 당사의 연락처(<a href="/en-US/docs/Learn#Contact_us">Contact us</a>) 섹션을 참조하는 것입니다.</p> + +<p>당신의 기사를 마무리하는 또 다른 방법은 학습 영역 기본 탐색 메뉴에 넣는 것입니다. 이 메뉴는 LearnSidebar 매크로에 의해 생성되어 편집할 특별한 권한이 필요합니다. 따라서 팀에서 추가한 내용에 대해 다시 한번 말씀 드리겠습니다.</p> + +<p>당신의 페이지에 기사를 추가해야 합니다. 이것은 당신의 페이지 맨 위에 있는 단락에 매크로(\{{LearnSidebar}})를 추가함으로써 이루어집니다.</p> + +<ul> +</ul> + +<h2 id="추천_기사">추천 기사</h2> + +<p>기여를 하고 싶은데 어떤 것을 써야 할 지를 모르겠나요?</p> + +<p>학습 영역 팀은 글을 쓰기 위한 아이디어가 담긴 트렐로 보드(<a href="https://trello.com/b/LDggrYSV">a Trello board with ideas of articles</a>)를 유지합니다. 하나를 골라서 자유롭게 작성하세요! </p> diff --git a/files/ko/mdn/contribute/howto/살아있는_코드_샘플로_변환하기/index.html b/files/ko/mdn/contribute/howto/살아있는_코드_샘플로_변환하기/index.html new file mode 100644 index 0000000000..27ac6774f1 --- /dev/null +++ b/files/ko/mdn/contribute/howto/살아있는_코드_샘플로_변환하기/index.html @@ -0,0 +1,39 @@ +--- +title: '"살아있는" 코드 샘플로 변환하기' +slug: MDN/Contribute/Howto/살아있는_코드_샘플로_변환하기 +tags: + - 라이브샘플 + - 살아있는 코드 + - 샘플코드 +translation_of: MDN/Contribute/Howto/Convert_code_samples_to_be_live +--- +<div>{{MDNSidebar}}</div><p class="summary">MDN의 라이브 샘플 시스템이란, 페이지에서 보여주는 샘플 코드를 수정하면 이 샘플 코드의 실행 결과도 달라지는 기능을 말합니다. 많은 문서에 샘플 코드들이 있지만 모든 샘플이 이 시스템을 사용하고 있지는 않으며, 생명력을 불어 넣어줘야 합니다.</p> +<table class="full-width-table"> + <tbody> + <tr> + <td><strong>어디서부터 시작해야 하나요?</strong></td> + <td><a href="/en-US/docs/tag/NeedsLiveSample">라이브 샘플이 필요한 글 목록</a>을 참고하세요.</td> + </tr> + <tr> + <td><strong>작업을 위해 알아 두어야 할 사항은 무엇인가요?</strong></td> + <td> + <ul> + <li>HTML, CSS에 대한 이해가 필요합니다. 샘플에 따라 JavaScript에 대한 지식을 요구할 수도 있습니다.</li> + <li>MDN 문서 내에서 <a href="/en-US/docs/Project:Introduction_to_KumaScript">쿠마 스크립트<sup>(en)</sup></a> 매크로를 사용할 수 있어야 합니다.</li> + </ul> + </td> + </tr> + <tr> + <td><strong>작업 진행 절차는 어떻게 되나요?</strong></td> + <td> + <p>라이브 샘플을 삽입하는 방법을 포함하여, 올바른 라이브 샘플을 작성하려면 <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide/Live_samples">라이브 샘플 시스템 사용하기<sup>(en)</sup></a> 문서를 참고하세요.</p> + <ol> + <li><a href="/en-US/docs/tag/NeedsLiveSample">라이브 샘플이 필요한 글 목록</a>에서 마음에 드는 글을 고르세요.</li> + <li>샘플에 "생명력을 불어 넣으세요".</li> + <li>과거의 것들은 지워버리세요.</li> + </ol> + </td> + </tr> + </tbody> +</table> +<p> </p> diff --git a/files/ko/mdn/contribute/index.html b/files/ko/mdn/contribute/index.html new file mode 100644 index 0000000000..530c096b40 --- /dev/null +++ b/files/ko/mdn/contribute/index.html @@ -0,0 +1,17 @@ +--- +title: MDN에 참여하기 +slug: MDN/Contribute +tags: + - MDN 메타 + - 가이드 + - 시작하기 + - 참고문서 +translation_of: MDN/Contribute +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>환영합니다! 이 페이지를 방문함으로써 당신은 MDN의 공헌자가 되기 위한 한 발을 내딛으셨습니다! <span class="seoSummary">아래의 가이드 목록은 스타일 가이드와, 저희의 에디터와 툴 사용설명서 등 MDN에 공헌하기 위한 모든 내용을 담고 있습니다. 페이지를 수정하거나 추가하기 전에 꼭 <a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/">Mozilla 법적 고지</a>를 읽고 숙지하시길 바랍니다.</span></p> + +<p>아직 MDN에 기여해본 경험이 없다면 <a href="/ko/docs/MDN/Getting_started">시작하기</a> 가이드가 당신이 첫번째 기여할 일을 찾는데 도움이 될 것입니다.</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ko/mdn/contribute/processes/index.html b/files/ko/mdn/contribute/processes/index.html new file mode 100644 index 0000000000..3e4e733a6a --- /dev/null +++ b/files/ko/mdn/contribute/processes/index.html @@ -0,0 +1,16 @@ +--- +title: 문서 작업 절차 +slug: MDN/Contribute/Processes +tags: + - MDN 메타 + - 시작하기 + - 프로세스 +translation_of: MDN/Contribute/Processes +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<div>MDN 문서 프로젝트는 전세계의 수많은 공로자들의 도움으로 엄청난량의 기술 문서를 구축했습니다. 문서량이 많아서 생기는 혼란을 줄이기 위해서 문서 수정 시 지켜야 할 표준 절차를 마련했습니다. 다음 가이드를 참고하세요. </div> + +<div> </div> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ko/mdn/editor/index.html b/files/ko/mdn/editor/index.html new file mode 100644 index 0000000000..a327f0fd89 --- /dev/null +++ b/files/ko/mdn/editor/index.html @@ -0,0 +1,19 @@ +--- +title: MDN 에디터 UI 가이드 +slug: MDN/Editor +tags: + - Landing + - MDN +translation_of: MDN/Editor +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("ko/docs/MDN")}}</div> + +<p><span class="seoSummary">MDN 위키가 제공하는 위지윅(WYSIWYG) 에디터를 통해 새로운 컨텐츠에 쉽게 기여할 수 있습니다. 이 글은 에디터의 사용법과 작업 생산성을 향상시킬 수 있는 기능들에 대해 상세히 설명하고 있습니다. 새로운 페이지를 생성하거나 편집하기 전에 <a href="/ko/about/legal/terms/mozilla/">모질라의 법적고지</a>를 읽고 여기에 따라주십시오.</span></p> + +<p><a href="/ko/docs/MDN/Contribute/Content/Style_guide" title="/en-US/docs/Project:MDN/Style_guide">MDN 스타일 지침</a>을 통해 MDN이 지향하는 형식, 스타일, 선호하는 문법과 스펠링 규칙에 대해 자세히 알 수 있습니다.</p> + +<p>{{LandingPageListSubpages}}</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ko/mdn/editor/links/index.html b/files/ko/mdn/editor/links/index.html new file mode 100644 index 0000000000..f6217db92c --- /dev/null +++ b/files/ko/mdn/editor/links/index.html @@ -0,0 +1,181 @@ +--- +title: Links +slug: MDN/Editor/Links +tags: + - MDN + - 가이드 + - 문서화 + - 에디터 +translation_of: MDN/Editor/Links +--- +<div>{{MDNSidebar}}</div> + +<p id="Creating_and_editing_links"><span class="seoSummary">링크는 어떤 위키에서나 가장 중요한 요소입니다. 그 중요성은 많은 문서간에서 뿐만 아니라, 단일 문서에서도 동일합니다. MDN 또한 링크에 크게 의존하고 있습니다. 다행스럽게도, 링크는 만들 수있는 방법이 많으면서도, 매우 만들기 쉽습니다!</span></p> + +<div class="note"> +<p><strong>주목할 점:</strong> 특별히 <a href="/ko/docs/MDN/Contribute/Guidelines/Writing_style_guide#링크">링크시에 선호되는 작성방법</a>이 있습니다; <a href="/ko/docs/MDN/Contribute/Guidelines/Writing_style_guide">MDN 작성 스타일 가이드</a>에 설명되어 있습니다.</p> +</div> + +<h2 id="툴바_사용하기">툴바 사용하기</h2> + +<p>링크를 만드는 가장 확실한 방법은 툴바의 "link" 버튼을 클릭하거나, <kbd>Ctl</kbd>+<kbd>K</kbd> (맥에서는 <kbd>Command</kbd>-<kbd>K</kbd> )를 누르는 것입니다. 링크 버튼은 이렇게 생겼습니다: <img alt="The link button (as of 2015-12-04)" src="https://mdn.mozillademos.org/files/12003/link-button.png" style="height: 16px; width: 16px;">. 문자열 선택없이 링크 작성시에, 혹은 기존에 있는 문자열을 선택하여 링크 작성시에 이 기능을 이용할 수 있습니다.</p> + +<h3 id="문자열_선택없이_링크_작성하기">문자열 선택없이 링크 작성하기</h3> + +<p>일단 링크 버튼을 클릭하면, 아래에 보이는 링크 에디터 다이얼로그로 진입합니다:</p> + +<p><img alt="Screenshot of the Link dialog box, showing the Link Info tab" src="https://mdn.mozillademos.org/files/15289/link-info.png" style="border-style: solid; border-width: 1px; height: 320px; width: 335px;"></p> + +<p>여기서 새로운 링크를 구성할 수 있습니다. 이 다이얼로그의 콘트롤은 다음과 같습니다:</p> + +<dl> + <dt>링크 종류</dt> + <dd>생성중인 링크의 종류입니다. URL의 기본값은, MDN이든 오프사이트이든, 웹상 어딘가에 있는 URL입니다. 텍스트내의 앵커 (anchor)또는 "이메일"을 선택할 수도 있습니다. 앵커 링크 옵션은 툴바의 <strong>Anchor</strong> 버튼 으로 이전에 삽입된 anchor로의 링크를, 목록에서 골라서 생성할 수 있도록 합니다. 이메일 옵션은 받는사람의 이메일 주소와 제목 기본 메시지 콘텐츠를 입력하여 <code>mailto:</code> URL 이 구성되도록 합니다. 대부분의 경우 URL optin을 사용하게 될 겁니다.</dd> + <dt>문서 제목 찾기 / 링크 텍스트</dt> + <dd>이 필드는 두가지 목적을 수행합니다: 첫째는, 링크 대상으로 사용할 텍스트를 지정할 수 있습니다 (또는 대화 상자를 열기 전에 텍스트를 선택한 경우, 해당 텍스트가 이곳에 링크 대상으로 표시됩니다). 두번째로, 이 곳에 입력된 텍스트를 MDN내 등록된 문서와 대조하여 가능한 목적지 페이지를 찾아내는데 사용됩니다. 예를 들어, 이 박스안에 "Array"라고 타이핑하면, 아래와 같은 상황을 볼 수 있습니다:<br> + <img alt='Screenshot of the Link dialog box, showing a lookup menu for the text "Array"' src="https://mdn.mozillademos.org/files/15291/link%20dialog%20with%20lookup%20menu.png" style="border-style: solid; border-width: 1px; height: 388px; width: 496px;"></dd> +</dl> + +<dl> + <dd>Here, you can see a list of all the pages on MDN whose titles include the text you've typed. You can then scroll through the list and select one of those pages, or keep typing to narrow down the list. Note that the items in the list display their locale ("[en-US]" in this case). That text is not used in the link target text; it is there to help you ensure that you are linking to an article in the same locale as the one you are editing.</dd> + <dt>Attachments</dt> + <dd>Alternatively, you may make the link be a link to one of the files attached to the current page by selecting the attachment from this list. This is a great way to offer links to download code samples and the like.</dd> + <dt>URL</dt> + <dd>Finally, the URL field lets you actually directly enter the URL; it also shows the URL of whatever you've selected in either the <strong>Article Title Lookup</strong> or <strong>Attachments</strong> menus, if you've used those. A common practice is to paste URLs to pages you're working on elsewhere on MDN. If you link to another article on MDN, remove the domain name ("https://developer.mozilla.org") from the beginning of the URL, since that's implied.</dd> +</dl> + +<p>Once the link is configured, click the <strong>OK</strong> button to insert it.</p> + +<div class="note"> +<p>If you're paying attention, you'll see that there's a second tab—<strong>Advanced</strong>—in the link editor dialog. There are no options there that we advise you to use on a regular basis, at least at this time. It's possible that in the future there will be alternate styles for links, but we will likely add new toolbar widgets to use those features when they're available.</p> +</div> + +<h3 id="기존_텍스트에_링크_생성하기">기존 텍스트에 링크 생성하기</h3> + +<p>If you have existing text that you'd like to turn into a link, you can simplify the process somewhat. Highlight the text you'd like to turn into a link before opening the link editor; this will pre-populate the <strong>Article Title/Lookup Text</strong> field with the selected text. For example, let's say we have the following text:</p> + +<blockquote> +<p>You may find it useful to use JavaScript arrays when working on this project.</p> +</blockquote> + +<p>We'd like to turn "arrays" into a link to the appropriate content. Just highlight that word and invoke the link editor; you'll get a pre-populated dialog similar to the previous case. By "hovering" your mouse over a suggested article, you can see its relative slug (its URL relative to <code>developer.mozilla.org</code>), which can give you a better idea of where it is located and what type of article it is.</p> + +<p><img alt="Screenshot of the Link dialog box, showing a lookup menu and a URL tooltip" src="https://mdn.mozillademos.org/files/15293/Rollover%20of%20lookup%20menu.png" style="border-style: solid; border-width: 1px; height: 387px; width: 493px;"></p> + +<p>Here, of the articles suggested as possible matches. "Arrays" looks like a good choice, so we can choose that. This automatically fills in the URL field, so you can just click <strong>OK</strong> and the text gets turned into a link, like this:</p> + +<blockquote> +<p>You may find it useful to use JavaScript <a href="/en-US/docs/Learn/JavaScript/First_steps/Arrays">arrays</a> when working on this project.</p> +</blockquote> + +<h2 id="링크_매크로_사용하기">링크 매크로 사용하기</h2> + +<p>MDN은, 선택된 용어에 적절한 콘텐츠로의 링크가 자동적으로 생성되는 동시에 스타일 가이드에 맞게 링크가 생성되도록 하는 작업을 <a href="/ko/docs/Project:MDN/Contributing/Editor_guide#Using_macros">매크로</a>에 크게 의존합니다. 이 예를 보세요: 우리의 스타일 가이드는 API 용어 이름, HTML 요소와 속성, CSS 속성, 함수 이름등이 {{HTMLElement("code")}} 형식을 권장한다( 사실상 그대로 되어야 합니다)라고 되어있습니다. 그것들은 또한 MDN상의 적절한 페이지로 링크가 연결되어있어야 합니다.</p> + +<p>매크로를 이용하여 이런 링크들을 만드는 것은 익숙해지기에 약간 시간이 걸리지만 많은 장점이 있습니다:</p> + +<ul> + <li>당신이 의도한 알맞은 스타일이 적용됩니다.</li> + <li>링크는 당신을 위해 생성되며 - 미래에 MDN 구성이 변경되더라도 미래 환경에 적응됩니다.</li> + <li>역시 당신에게 알맞은 툴팁이 생성될 수 있습니다.</li> +</ul> + +<p>이런 종류의 매크로가 많이 있으며, 여기서 모든 매크로를 다 보지는 않을 겁니다. 대신, 가장 일반적인 몇가지 특별한 예를 살펴볼 것입니다. 더 완벽한 목록은 <a href="/en-US/docs/Project:MDN/Contributing/Custom_macros">MDN 커스텀 매크로 </a>가이드의 "<a href="/en-US/docs/Project:MDN/Contributing/Custom_macros#Creating_hyperlinks">하이퍼링크 생성하기</a>" 섹션을 보세요. 모든 매크로에 대해서 <a href="/ko/docs/Project:Introduction_to_KumaScript">KumaScript</a> 소스 코드를 확인할 수 있다는 점은 주목할만 합니다. 대부분의 경우 소스코드 상단에 작동 방식과 다양한 매개변수가 무엏인지 설명하는 주석이 있습니다.</p> + +<h3 id="API_문서에_링크걸기">API 문서에 링크걸기</h3> + +<p>We have a number of extremely helpful macros for creating styled links to APIs. Here are a few of the most useful ones; in each case, there may be added parameters available to give you more control over the output (such as suppressing the automatic addition of the <code><code></code> styling). Each macro name below can be clicked upon to read the macro code itself; they all have comments at the top explaining what they do and all of their parameters.</p> + +<dl> + <dt>{{TemplateLink("HTMLElement")}}</dt> + <dd>Inserts an HTML element's name, properly styled and linked. For example: <code>\{{HTMLElement("table")}}</code> yields {{HTMLElement("table")}}.</dd> + <dt>{{TemplateLink("cssxref")}}</dt> + <dd>Inserts a CSS property, at-rule, or selector's documentation in the CSS reference. For example: <code>\{{cssxref("background-color")}}</code> results in {{cssxref("background-color")}}.</dd> + <dt>{{TemplateLink("domxref")}}</dt> + <dd>Inserts a link into the Web API Reference for a given API term. For example: <code>\{{domxref("window")}}</code> yields {{domxref("window")}} and <code>\{{domxref("window.scrollBy()")}}</code> inserts {{domxref("window.scrollBy()")}}. You can also supply an additional parameter to override the text: <code>\{{domxref("window.scrollBy", "scrollBy()")}}</code> results in {{domxref("window.scrollBy", "scrollBy()")}}.</dd> + <dt>{{TemplateLink("SVGElement")}}</dt> + <dd>Inserts an SVG element's name, properly styled and linked. For example: <code>\{{SVGElement("circle")}}</code> yields {{SVGElement("circle")}}.</dd> +</dl> + +<h3 id="동일_문서내_섹션에_링크걸기">동일 문서내 섹션에 링크걸기</h3> + +<p>To link to a section within the same article, you can use the {{TemplateLink("anch")}} macro. The syntax is straightforward: <code>\{{anch("Name of destination section")}}</code>. By default, the displayed link text is the title of that section, but you can add a second, optional, parameter indicating alternate text to use instead. Some examples:</p> + +<ul> + <li><code>\{{anch("Using the toolbar")}}</code> looks like this: {{anch("Using the toolbar")}}</li> + <li><code>\{{anch("Using the toolbar", "earlier in this article")}}</code> looks like this: {{anch("Using the toolbar", "earlier in this article")}}</li> +</ul> + +<h3 id="버그에_링크걸기">버그에 링크걸기</h3> + +<p>You can link to a bug in Mozilla's Bugzilla database with the {{TemplateLink("bug")}} macro. This macro accepts a single parameter: the bug number to link to. For example, <code>\{{bug(765642)}}</code> looks like this: {{bug(765642)}}.</p> + +<p>Similarly, you can create links to bugs in other browsers and Web engines:</p> + +<dl> + <dt>WebKit (Safari, etc.)</dt> + <dd>{{TemplateLink("WebkitBug")}}: <code>\{{webkitbug(31277)}}</code> yields {{webkitbug(31277)}}.</dd> +</dl> + +<h3 id="RFCs_에_링크걸기">RFCs 에 링크걸기</h3> + +<p>Much of the way the Internet works at a core level is documented in RFCs. You can easily reference RFCs using the {{TemplateLink("RFC")}} macro. For example, \{{RFC(2616)}} becomes {{RFC(2616)}}. You can, optionally, also provide alternate link text to use instead of a selected piece of text from the article or and/or the section number within the specification to which to link.</p> + +<h3 id="XPCOM_인터페이스_정보에_링크걸기">XPCOM 인터페이스 정보에 링크걸기 </h3> + +<div class="note"> +<p>The MDN staff no longer actively maintains the XPCOM documentation, but volunteer contributions are welcomel</p> +</div> + +<p>If you're documenting Mozilla internals, being able to easily create links to XPCOM interface documentation is helpful. There are a few macros used for this.</p> + +<p>The syntax for linking to the documentation for an XPCOM interface as a whole is just: <code>\{{interface("interfacename")}}</code>. For example, you might write:</p> + +<blockquote> +<p>When you need to parse or create URIs, the \{{interface("nsIIOService")}} interface can help.</p> +</blockquote> + +<p>The result looks like this:</p> + +<blockquote> +<p>When you need to parse or create URIs, the {{interface("nsIIOService")}} interface can help.</p> +</blockquote> + +<p>If you need to link to information about a specific method or attribute on an XPCOM interface, the {{TemplateLink("ifmethod")}} and {{TemplateLink("ifattribute")}} macros are for you. These accept as parameters the name of the interface and the name of the method or attribute to which you wish to reference. The {{TemplateLink("ifmethod")}} macro is particularly interesting, since it does some special formatting by adding the style guide-mandated parentheses after the method's name. For example, <code>\{{ifmethod("nsIIOService", "newURI")}}</code> results in {{ifmethod("nsIIOService", "newURI")}}. That's a case where you're being protected against possible changes in the style guide in the future!</p> + +<h3 id="Mozilla_설정_문서에_링크걸기">Mozilla 설정 문서에 링크걸기</h3> + +<p>To insert the name of a Mozilla preference and make it link to the corresponding page in the <a href="/en-US/docs/Mozilla/Preferences/Preference_reference">Preference reference</a>, use the {{TemplateLink("pref")}} macro. This accepts one parameter: the full name of the preference you wish to link to. For example, you can use <code>\{{pref("javascript.options.showInConsole")}}</code> to create this: {{pref("javascript.options.showInConsole")}}.</p> + +<h3 id="Mozilla_소스_파일에_링크걸기">Mozilla 소스 파일에 링크걸기</h3> + +<p>You can link to files in Mozilla's source tree (although you probably won't do this often) using the {{TemplateLink("source")}} macro. Instead of specifying the full URL of the file, you can simply specify the path relative to the <code>/source/</code> directory. For example: \{{source("browser/Makefile.in")}} creates this link: {{source("browser/Makefile.in")}}.</p> + +<p>You may also, optionally, specify alternative text to use for the link. For example, you can use \{{source("browser/Makefile.in", "the browser's makefile")}} to get the result: {{source("browser/Makefile.in", "the browser's makefile")}}.</p> + +<div class="note"> +<p>Please look at the {{anch("Using macros")}} documentation if you're interested in learning more about using macros, and check out our <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a> documentation to learn more about the macro system itself.</p> +</div> + +<h2 id="추천_콘텐츠에_링크걸기">추천 콘텐츠에 링크걸기</h2> + +<p>If you wish to create a list of related pages, or other recommended reading material, you should do so by creating a quicklinks box in the sidebar; this mechanism is replacing our old "See also" headings at the end of articles. For details on how to create quicklinks boxes, see <a href="/en-US/docs/MDN/Contribute/Structures/Quicklinks">Quicklinks</a>.</p> + +<h2 id="URL_정책">URL 정책</h2> + +<p>For security reasons, you should only create links that use the following schemes:</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>Others may or may not work, but are not supported and will probably be removed by editorial staff.</p> + +<div class="note"> +<p>Special URL schemes such as <code>about:</code> and <code>chrome:</code> are used by Firefox, Google Chrome, and some other browsers to provide access to special content such as preferences, debugging information, and so forth. These links do not work from article content, so please do not try to create links using these schemes within MDN articles. The same applies to the <code>javascript:</code> and <code>jar:</code> schemes, which are blocked by most modern browsers as a security precaution.</p> +</div> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ko/mdn/guidelines/best_practices/index.html b/files/ko/mdn/guidelines/best_practices/index.html new file mode 100644 index 0000000000..d8c5f2b247 --- /dev/null +++ b/files/ko/mdn/guidelines/best_practices/index.html @@ -0,0 +1,34 @@ +--- +title: 모범 사례 +slug: MDN/Guidelines/Best_practices +tags: + - Guide + - Guidelines + - MDN Meta +translation_of: MDN/Guidelines/Conventions_definitions +--- +<div>{{MDNSidebar}}</div><p>이 글은 MDN에서 추천하는 콘텐츠 작업 법을 설명합니다. 이 가이드라인은 더 나은 결과로 이끌 선호하는 일하는 법을 설명하거나 비슷한 일을 하는 여러 방법 중에서 결정에 조언을 제공합니다.</p> + +<h2 id="콘텐츠_복사하기">콘텐츠 복사하기</h2> + +<p>때때로, 여러 페이지에 같은 텍스트를 재사용해야 합니다 (또는 한 페이지의 콘텐츠를 다른 페이지를 위한 템플릿으로 사용하고 싶습니다). 세 가지 선택 사항이 있습니다:</p> + +<ul> + <li>전체 페이지를 복사하고 싶다면: + <ol> + <li>복사하고 싶은 페이지를 보는 동안, <strong>고급</strong> (톱니바퀴) 메뉴의 <strong><a href="/ko/docs/MDN/Contribute/Creating_and_editing_pages#Clone_of_an_existing_page" title="Clone this article">이 글 복제</a></strong>를 고르세요. 이는 새 페이지를 위한 편집기 UI를 엽니다, 복제된 페이지의 콘텐츠로 이미 채워진 채로.</li> + <li>복제된 페이지를 위한 새로운 <strong>한국어 제목</strong> 및 <strong>슬러그</strong>를 입력하세요.</li> + <li>필요에 따라 페이지의 콘텐츠를 편집하고 평소대로 저장하세요.</li> + </ol> + </li> + <li>페이지의 일부만 복사하고 싶은 경우, <strong>페이지를 방문만 하지 말고 거기서 복사하세요</strong>. 이는 원치 않는 추가 HTML 조각을 목적 페이지에 끼워 넣고 누군가는 이를 정리해야 합니다, 당신 또는 다른 편집자가. 아무도 그것을 원하지 않습니다. MDN 페이지의 일부를 다른 페이지로 복사하려면: + <ol> + <li>소스 페이지에서, 소스 페이지의 <strong>편집</strong> 버튼을 클릭하세요.</li> + <li><strong>편집기 UI 내에서 재사용하고 싶은 콘텐츠를 복사하세요.</strong></li> + <li>그 페이지를 위한 편집기 UI를 빠져나오기 위해 <strong>Discard</strong> 클릭하세요.</li> + <li>붙여 넣고 싶은 페이지를 위한 편집기 UI를 여세요.</li> + <li>클립보드에서 콘텐츠를 붙여 넣으세요.</li> + </ol> + </li> + <li>때때로 말 그대로 많은 페이지에 같은 콘텐츠를 사용하고 싶습니다. 이 경우에, 한 페이지에 콘텐츠를 두고, 그 뒤에 한 페이지에서 다른 페이지로 내용물을 삽입참조(transclude)하는 {{TemplateLink("Page")}} 매크로를 사용하는 것이 최선이 될 수 있습니다. 이런 식으로 하면, 소스 페이지의 텍스트가 갱신될 때마다, 대상 페이지도 갱신됩니다 (즉, 이는 강제-새로고침 또는 대상 페이지가 예정된 재빌드가 이루어질 때 일어납니다).</li> +</ul> diff --git a/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html b/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html new file mode 100644 index 0000000000..093f50ae47 --- /dev/null +++ b/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html @@ -0,0 +1,159 @@ +--- +title: 모든 코드에 대한 일반 가이드라인 +slug: MDN/Guidelines/Code_guidelines/Code_guidelines +tags: + - Code + - General + - Guide + - MDN Meta + - 가이드 + - 가이드라인 + - 코드 블럭 + - 코드 블록 + - 코드 스타일 +translation_of: MDN/Guidelines/Code_guidelines/General +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p class="summary">아래 코드 예제 가이드라인에서 HTML, CSS, JavaScript 나 다른 어느 코드로 예로 들건 , 모든 코드 타입에 적용됩니다.</p> + +<h2 id="이_문서_내용은"> 이 문서 내용은</h2> + +<ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#들여쓰기_여백주기_사이즈">들여쓰기, 여백주기, 사이즈</a> + + <ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#들여쓰기">들여쓰기</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#코드_한_줄_길이">코드 한 줄 길이</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#코드_블럭_높이">코드 블럭 높이</a></li> + </ul> + </li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#예제_디스플레이_가이드라인">예제 디스플레이 가이드라인</a> + <ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#렌더링_된_예제_크기">렌더링 된 예제 크기</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#이미지나_다른_미디어의_사용">이미지나 다른 미디어의 사용</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#컬러의_사용">컬러의 사용</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#좋은_예시와_나쁜_예시_강조">좋은 예시와 나쁜 예시 강조</a></li> + </ul> + </li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#레퍼런스_페이지에서_문법_섹션_작성">레퍼런스 페이지에 문법 섹션 작성</a></li> +</ul> + +<h2 id="들여쓰기_여백주기_사이즈">들여쓰기, 여백주기, 사이즈</h2> + +<h3 id="들여쓰기">들여쓰기</h3> + +<p>모든 코드는 2 스페이스로 들여쓰기 해야합니다. 예를 들면:</p> + +<pre class="brush: html example-good notranslate"><div> + <p>This is my paragraph.</p> +</div></pre> + +<pre class="brush: js example-good notranslate">function myFunc() { + if(thingy) { + console.log('Yup, that worked.'); + } +}</pre> + +<h3 id="코드_한_줄_길이">코드 한 줄 길이</h3> + +<p>한 행의 코드는 최대 80자 (<a href="https://github.com/mdn/interactive-examples">대화형 예제</a>는 64자) 이내로 제한 되어야 합니다. 가독성을 위해 합리적으로 행을 분리 하는 것 좋지만 모범 사례를 벗어나지는 마십시오.</p> + +<p>예를 들면, 아래는 안 좋은 예입니다.</p> + +<pre class="brush: js example-bad notranslate">let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.';</pre> + +<p>이것은 좀 낫지만, 그래도 여전히 좋지 않습니다:</p> + +<pre class="brush: js notranslate">let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign ' ++ 'matter may have nestled its way into his mighty throat. Many a fat alley rat ' ++ 'had met its demise while staring point blank down the cavernous barrel of ' ++ 'this awesome prowling machine.';</pre> + +<p>템플릿 리터럴을 사용하는 것이 더 좋습니다:</p> + +<pre class="brush: js example-good notranslate">let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign + matter may have nestled its way into his mighty throat. Many a fat alley rat + had met its demise while staring point blank down the cavernous barrel of + this awesome prowling machine.`;</pre> + +<h3 id="코드_블럭_높이">코드 블럭 높이</h3> + +<p>코드 블럭은 필요한 만큼 길어야 하지만 너무 길면 안됩니다. 15에서 25 라인 정도의 길이가 이상적입니다. 코드 블럭이 너무 길어진다면, 가장 유용한 스니펫만 보여주고, 나머지 부분은 깃허브 저장소나 코드펜 같은 링크로 연결하세요.</p> + +<h2 id="예제_디스플레이_가이드라인">예제 디스플레이 가이드라인</h2> + +<h3 id="렌더링_된_예제_크기">렌더링 된 예제 크기</h3> + +<p>MDN 메인 콘텐츠 창은 데스크탑에서 약 700px 크기 이므로, 삽입된 MDN 예제는 ( 삽입된 예제를 100% 너비로 설정했을 때 ) 해당 너비에서 잘 보여야 합니다.</p> + +<p>높이의 경우, 최대한의 화면 가독성을 위해 가능하면 렌더링 된 예제 높이를 700px 아래로 유지하는 것을 추천합니다.</p> + +<p>모바일 디바이스에서도 예제가 잘 보이도록 어느 정도는 반응형으로 동작되도록 예제를 작성하는데 신경써야 합니다.</p> + +<h3 id="이미지나_다른_미디어의_사용">이미지나 다른 미디어의 사용</h3> + +<p>가끔 이미지나 다른 미디어를 예제에 삽입하고 싶을 때가 있습니다. 그럴 때에는:</p> + +<ul> + <li>해당 미디어의 라이센스가 사용을 허용하는지 확인하세요. <a href="https://creativecommons.org/share-your-work/public-domain/cc0/" rel="nofollow">CC0</a>와 같은 매우 관대한 라이브러리나, 적어도 일반적인 콘텐츠 라이센스인 <a class="external text external-icon" href="http://creativecommons.org/licenses/by-sa/2.5/" rel="nofollow noopener" title="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons Attribution-ShareAlike license</a> (CC-BY-SA) 중 하나를 사용하도록 해야합니다.</li> + <li>이미지에 대해서는, <a href="https://tinypng.com" rel="nofollow">https://tinypng.com</a> 나 <a href="https://imageoptim.com" rel="nofollow">https://imageoptim.com</a> 를 사용해 예제의 페이지 무게를 줄여야 합니다.</li> + <li><code>SVG</code>에 대해서는, <a href="https://jakearchibald.github.io/svgomg/">SVGOMG</a>를 통해 <code>SVG</code> 파일이 파일 마지막에 빈 줄을 갖도록 해야합니다.</li> + <li> + <p>페이지에서 아이콘을 보여줄 때 (즉 {{cssxref("background-image")}} 를 이용할 때), 적당한 곳에 <a href="https://mdn.github.io/mdn-fiori/patterns/css/iconography/">빌트인 MDN 아이콘</a>을 사용하고, 다른 경우와 비교하여 스타일을 맞추도록 하십시오.</p> + </li> +</ul> + +<h3 id="컬러의_사용">컬러의 사용</h3> + +<p>소문자 16진수 대신, 음영이나 주요 컬러(즉, 검은색, 흰색, 빨간색)는 키워드를 사용할 수있습니다. 필요한 경우에만 좀 더 복잡한 컬러스킴을 사용하세요.( 예를 들면, 투명색이 필요할 때)</p> + +<p>주요 "기본" 컬러는 키워드로 설정하는것이 좋습니다. 예를 들면:</p> + +<pre class="brush: css example-good notranslate">color: black; +color: white; +color: red;</pre> + +<p>좀 더 복잡한 컬러는 rgb() 를 사용합니다. (반 투명 색 포함):</p> + +<pre class="brush: css example-good notranslate">color: rgb(0, 0, 0, 0.5); +color: rgb(248, 242, 230);</pre> + +<p>16진수 컬러를 사용해야 한다면, 소문자를 이용하세요:</p> + +<pre class="brush: css example-good notranslate">color: #058ed9; +color: #a39a92;</pre> + +<p>그리고 가능한 곳에는 단축형태를 사용하세요:</p> + +<pre class="brush: css example-good notranslate">color: #ff0; +color: #fff;</pre> + +<p><a href="https://mdn-fiori.netlify.app/">MDN's Fiori 가이드라인</a>(프론트엔드 코드베이스용)은 전체 MDN 디자인에 사용된 <a href="https://mdn-fiori.netlify.app/?path=/docs/docs-colors--page">유용한 컬러셋</a>을 포함하고 있습니다. ( 역자주: 영어 원문 링크가 깨져 <a href="https://github.com/mdn/mdn-fiori">MDN Fiori 깃허브 리포</a> 에서 비슷한 링크를 찾아 연결했습니다.)</p> + +<h3 id="좋은_예시와_나쁜_예시_강조">좋은 예시와 나쁜 예시 강조</h3> + +<p>이 가이드라인에서 알 수 있는 것처럼, 좋은 실습예시는 연두색에 웃는얼굴로 강조되며, 나쁜 실습 예시는 슬픈표정에 빨간 바탕으로 강조됩니다.</p> + +<p>이 처럼 하려면, MDN 에디터 콘트롤로 코드 블럭을 <code><pre></code> 블럭이 되도록 하고, 적절한 문법 강조를 설정해야 합니다. 소스 코드는 아래와 비슷하게 보일겁니다:</p> + +<pre class="notranslate"><pre class="brush: js"> +function myFunc() { + console.log('Hello!'); +};</pre></pre> + +<p>이 상태에서 좋은 예시로 만들려면, <code>class</code> 속성의 오른쪽 따옴표 바로 앞에 <code>example-good</code>을 넣으면 됩니다:</p> + +<pre class="notranslate"><pre class="brush: js example-good"> + ...</pre> + +<p>나쁜 예시로 만들려면, <code>class</code> 속성의 오른쪽 따옴표 바로 앞에 <code>example-bad</code>를 넣으면 됩니다:</p> + +<pre class="notranslate"><pre class="brush: js example-bad"> + ...</pre> + +<p>우리는 당신이 이 기능을 사용하길 권장합니다. 모든 곳에 사용할 필요는 없습니다. 당신의 코드에서 좋은 예와 나쁜 예를 구분할 필요가 있을때 사용하세요.</p> + +<h2 id="레퍼런스_페이지에서_문법_섹션_작성">레퍼런스 페이지에서 문법 섹션 작성</h2> + +<p>MDN 레퍼런스 페이지에는 JavaScript 메서드, CSS 속성, HTML 요소 등과 같이 기능의 구문이 무엇을 할 수 있고, 어때야 하는지 명확하게 보여주는 문법 섹션(Syntax section)이 포함되어 있습니다. 이 내용을 작성하는 가이드라인은 <a href="/ko/docs/MDN/Contribute/Structures/Syntax_sections">Syntax sections</a> 문서를 참고하세요.</p> diff --git a/files/ko/mdn/guidelines/code_guidelines/css/index.html b/files/ko/mdn/guidelines/code_guidelines/css/index.html new file mode 100644 index 0000000000..cbcbd11ae8 --- /dev/null +++ b/files/ko/mdn/guidelines/code_guidelines/css/index.html @@ -0,0 +1,249 @@ +--- +title: CSS 가이드라인 +slug: MDN/Guidelines/Code_guidelines/CSS +translation_of: MDN/Guidelines/Code_guidelines/CSS +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">다음 가이드라인은 MDN code 예제를 위한 CSS 작성 방법을 설명합니다.</p> + +<h2 id="이번_기사에서는">이번 기사에서는</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#High-level_guidelines">고급 가이드라인</a> + + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_preprocessors">전처리기를 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_specific_CSS_methodologies">특정 CSS 방법론을 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_flexiblerelative_units">유연하고/상대적인 단위를 사용합니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_resets">재설정을 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Plan_your_CSS_%E2%80%94_avoid_overriding">CSS 계획 — 재정의 (overriding) 를 방지합니다</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#General_CSS_coding_style">일반적인 CSS 코딩 스타일</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_expanded_syntax">확장 구문을 사용합니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Favor_longhand_rules_over_terse_shorthand">속기 (shorthand) 보다는 longhand 규칙을 좋아합니다</a> </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_double_quotes_around_values">값을 큰 따옴표로 묶습니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Spacing_around_function_parameters">함수 매개변수 주위의 간격</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#CSS_comments">CSS 주석</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_!important">!important 를 사용하지 마십시오</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Specific_CSS_syntax_points">특정 CSS 구문 포인트</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Turning_off_borders_and_other_properties">테두리 및 기타 속성 끄기</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_mobile_first_media_queries">"모바일 우선" 미디어 쿼리 사용</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Selectors">선택자</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_ID_selectors">ID 선택자를 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Put_multiple_selectors_on_separate_lines">여러 라인을 별도의 라인에 배치</a></li> + </ul> + </li> +</ul> + +<h2 id="High-level_guidelines">High-level guidelines</h2> + +<h3 id="Dont_use_preprocessors">Don't use preprocessors</h3> + +<p>Don't use preprocessor syntax, e.g. <a href="https://sass-lang.com/">Sass</a>, <a href="http://lesscss.org/">Less</a>, or <a href="http://stylus-lang.com/">Stylus,</a> in your MDN example code. MDN documents the vanilla CSS language, and using preprocessors only serves to raise the bar to understanding the examples, potentially confusing readers.</p> + +<h3 id="Dont_use_specific_CSS_methodologies">Don't use specific CSS methodologies</h3> + +<p>In the same spirit as the previous guideline, don't write MDN example code using a specific CSS methodology such as <a href="http://getbem.com/naming/">BEM</a> or <a href="https://smacss.com/">SMACSS</a>. Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies.</p> + +<h3 id="Use_flexiblerelative_units">Use flexible/relative units</h3> + +<p>For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems, or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our <a href="/en-US/docs/Web/Apps/app_layout/responsive_design_building_blocks#Fluid_grids">Responsive design building blocks</a> article.</p> + +<h3 id="Dont_use_resets">Don't use resets</h3> + +<p>For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world CSS resets can be overkill, resulting in lots of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc.</p> + +<p>If you really feel like you need to use a reset, consider using <a href="http://necolas.github.io/normalize.css/">normalize.css by Nicolas Gallagher</a>, which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on <code><body></code>, for example) and fix a few bugs.</p> + +<h3 id="Plan_your_CSS_—_avoid_overriding">Plan your CSS — avoid overriding</h3> + +<p>Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to avoid too much overriding. If you keep finding yourself writing styles and then cancelling them again a few rulesets down, you probably need to rethink your strategy.</p> + +<h2 id="General_CSS_coding_style">General CSS coding style</h2> + +<h3 id="Use_expanded_syntax">Use expanded syntax</h3> + +<p>There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN.</p> + +<p>Use this:</p> + +<pre class="brush: css example-good notranslate">p { + color: white; + background-color: black; + padding: 1rem; +}</pre> + +<p>Not this:</p> + +<pre class="brush: css example-bad notranslate">p { color: white; background-color: black; padding: 1rem; }</pre> + +<p>In addition, keep these specifics in mind:</p> + +<ul> + <li>Include a space between the selector(s) and the opening curly brace.</li> + <li>Always include a semi-colon at the end of the last declaration, even though it isn't strictly necessary.</li> + <li>Put the closing curly brace on a new line.</li> + <li>In each declaration, put a space after the separating colon, but not before.</li> + <li>Use 2 spaces for code indentation.</li> +</ul> + +<h3 id="Favor_longhand_rules_over_terse_shorthand">Favor longhand rules over terse shorthand</h3> + +<p>Usually when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless of course teaching the shorthand is the point of the example). Remember that the point of MDN examples is to teach people, not to be clever or efficient.</p> + +<p>To start with, it is often harder to understand what the shorthand is doing. It takes a while to pick apart exactly what {{cssxref("font")}} syntax is doing, for example:</p> + +<pre class="brush: css notranslate">font: small-caps bold 2rem/1.5 sans-serif;</pre> + +<p>Whereas this is more immediate in terms of understanding:</p> + +<pre class="brush: css notranslate">font-variant: small-caps; +font-weight: bold; +font-size: 2rem; +line-height: 1.5; +font-family: sans-serif;</pre> + +<p>Second, CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade, or other expected effects. The {{cssxref("grid")}} property for example sets all of the following default values for items that are not specified:</p> + +<ul> + <li>{{cssxref("grid-template-rows")}}: <code>none</code></li> + <li>{{cssxref("grid-template-columns")}}: <code>none</code></li> + <li>{{cssxref("grid-template-areas")}}: <code>none</code></li> + <li>{{cssxref("grid-auto-rows")}}: <code>auto</code></li> + <li>{{cssxref("grid-auto-columns")}}: <code>auto</code></li> + <li>{{cssxref("grid-auto-flow")}}: <code>row</code></li> + <li>{{cssxref("grid-column-gap")}}: <code>0</code></li> + <li>{{cssxref("grid-row-gap")}}: <code>0</code></li> + <li>{{cssxref("column-gap")}}: <code>normal</code></li> + <li>{{cssxref("row-gap")}}: <code>normal</code></li> +</ul> + +<p>In addition, some shorthands only work as expected if you include the different value components in a certain order. In CSS animations for example:</p> + +<pre class="brush: css notranslate">/* duration | timing-function | delay | iteration-count + direction | fill-mode | play-state | name */ +animation: 3s ease-in 1s 2 reverse both paused slidein;</pre> + +<p>As an example, the first value that can be parsed as a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/time" title="The <time> CSS data type represents a time value expressed in seconds or milliseconds. It is used in animation, transition, and related properties."><code><time></code></a> is assigned to the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/animation-duration" title="The animation-duration CSS property sets the length of time that an animation takes to complete one cycle."><code>animation-duration</code></a>, and the second one is assigned to <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/animation-delay" title="The animation-delay CSS property sets when an animation starts. The animation can start later, immediately from its beginning, or immediately and partway through the animation."><code>animation-delay</code></a>. For more details, read the full <a href="/en-US/docs/Web/CSS/animation#Syntax">animation syntax</a> details.</p> + +<h3 id="Use_double_quotes_around_values">Use double quotes around values</h3> + +<p>Where quotes can or should be included, use them, and use double quotes. For example:</p> + +<pre class="brush: css example-good notranslate">[data-vegetable="liquid"] { + background-color: goldenrod; + background-image: url("../../media/examples/lizard.png"); +}</pre> + +<h3 id="Spacing_around_function_parameters">Spacing around function parameters</h3> + +<p>Function parameters should have spaces after their separating commas, but not before:</p> + +<pre class="brush: css example-good notranslate">color: rgb(255, 0, 0); +background-image: linear-gradient(to bottom, red, black);</pre> + +<h3 id="CSS_comments">CSS comments</h3> + +<p>Use CSS-style comments to comment code that isn't self-documenting:</p> + +<pre class="brush: css example-good notranslate">/* This is a CSS-style comment */</pre> + +<p>Put your comments on separate lines preceeding the code they are referring to:</p> + +<pre class="brush: css example-good notranslate">h3 { + /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */ + text-shadow: 1px 1px 2px red; + /* Sets the font-size to double the default document font size */ + font-size: 2rem; +}</pre> + +<p>Also note that you should leave a space between the asterisks and the comment, in each case.</p> + +<h3 id="Dont_use_!important">Don't use !important</h3> + +<p>!important is a last resort generally only used when you need to override something and there is no other way. It is a bad practice and you should avoid it wherever possible.</p> + +<p>Bad:</p> + +<pre class="brush: css example-bad notranslate">.bad-code { + font-size: 4rem !important; +}</pre> + +<h2 id="Specific_CSS_syntax_points">Specific CSS syntax points</h2> + +<h3 id="Turning_off_borders_and_other_properties">Turning off borders and other properties</h3> + +<p>When turning off borders (and any other properties that can take <code>0</code> or <code>none</code> as values), use <code>0</code> rather than <code>none</code>:</p> + +<pre class="brush: css example-good notranslate">border: 0;</pre> + +<h3 id="Use_mobile_first_media_queries">Use "mobile first" media queries</h3> + +<p>When including different sets of styles for different target viewport sizes using media queries inside the same stylesheet, it is a good idea to make the default styling before any media queries have been applied to the document the narrow screen/mobile styling, and then override this for wider viewports inside successive media queries.</p> + +<pre class="brush: css example-good notranslate">/*Default CSS layout for narrow screens*/ + +@media (min-width: 480px) { + /*CSS for medium width screens*/ +} + +@media (min-width: 800px) { + /*CSS for wide screens*/ +} + +@media (min-width: 1100px) { + /*CSS for really wide screens*/ +}</pre> + +<p>This has many advantages, outlined in our <a href="/en-US/docs/Web/Apps/Progressive/Responsive/Mobile_first">Mobile First</a> article.</p> + +<h2 id="Selectors">Selectors</h2> + +<h3 id="Dont_use_ID_selectors">Don't use ID selectors</h3> + +<p>There is really no need to use ID selectors — they are less flexible (you can't add more if you discover you need more than one), and are harder to override if needed, being of a higher specificity than classes.</p> + +<p>Good:</p> + +<pre class="brush: css example-good notranslate">.editorial-summary { + ... +}</pre> + +<p>Bad:</p> + +<pre class="brush: css example-bad notranslate">#editorial-summary { + ... +}</pre> + +<h3 id="Put_multiple_selectors_on_separate_lines">Put multiple selectors on separate lines</h3> + +<p>When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read, and can help to make code lines shorter.</p> + +<p>Do this:</p> + +<pre class="brush: css example-good notranslate">h1, +h2, +h3 { + font-family: sans-serif; + text-align: center; +}</pre> + +<p>Not this:</p> + +<pre class="brush: css example-bad notranslate">h1, h2, h3 { + font-family: sans-serif; + text-align: center; +}</pre> + +<h2 id="Good_CSS_examples_on_MDN">Good CSS examples on MDN</h2> + +<p>You can find good, concise, meaningful CSS snippets at the top of our CSS property reference pages — browse through our <a href="/en-US/docs/Web/CSS/Reference#Keyword_index">CSS keyword index</a> to find some. Our interactive examples are generally written to follow the above guidelines, although be aware that they may differ in some places as they were mostly written before the guidelines were newly written.</p> diff --git a/files/ko/mdn/guidelines/code_guidelines/index.html b/files/ko/mdn/guidelines/code_guidelines/index.html new file mode 100644 index 0000000000..3ce931004f --- /dev/null +++ b/files/ko/mdn/guidelines/code_guidelines/index.html @@ -0,0 +1,80 @@ +--- +title: Code example guidelines +slug: MDN/Guidelines/Code_guidelines +tags: + - CSS + - Code + - Guide + - Guidelines + - HTML + - JavaScript + - MDN Meta + - NeedsTranslation + - Shell + - TopicStub +translation_of: MDN/Guidelines/Code_guidelines +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<div> +<p class="summary"><span class="seoSummary">This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN.</span></p> + +<p>If you are looking for guidelines to follow when writing your code examples, you have come to the right place. The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on MDN, which increases readability and comprehension overall.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our <a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide#Code_sample_style_and_formatting">Writing style guide</a>.</p> +</div> + +<h2 id="Article_structure">Article structure</h2> + +<p>This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows:</p> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General">General guidelines for all code</a> — both syntactical and for styling/displaying examples</li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML">HTML guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS">CSS guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript">JavaScript guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell">Shell prompt guidelines</a></li> +</ul> + +<h2 id="General_best_practices">General best practices</h2> + +<p>This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function.</p> + +<p>Code samples need to be:</p> + +<ul> + <li>simple enough to be understandable, but</li> + <li>complex enough to do something interesting, and preferably useful.</li> +</ul> + +<p>There is one overarching consideration that you need to keep in mind: <strong>Readers will copy and paste the code sample into their own code, and may put it into production.</strong></p> + +<p>Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and <strong>does not</strong> do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text — if it is a snippet and not a full example, make this clear. This also means that you should provide <strong>all</strong> of the information necessary to run the example including any dependencies and setup.</p> + +<p><span class="author-g-frc9o9ihh5c9qyd0">Code samples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible.</span></p> + +<ul> +</ul> + +<div id="magicdomid13"><span class="author-g-frc9o9ihh5c9qyd0">Guidelines:</span></div> + +<div id="magicdomid14"> </div> + +<div id="magicdomid15"> +<ul> + <li><span class="author-g-frc9o9ihh5c9qyd0">The sample should be short and ideally only show the feature you are immediately interested in.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0"><strong>Only</strong> include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the audience. If you want to provide a full, more lengthy, example put it in one of our <a href="https://github.com/mdn/">Github repos</a> (or a JSBin, Codepen, or similar) and then provide the link to the full version above or below the sample.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they make the code less portable, and harder to run and understand. Use vanilla code where possible.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't assume knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than classnames that make sense to BEM or Bootstrap users.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't use bad practices for brevity (such as presentational elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">In the case of API demos, if you are using multiple APIs together point out what APIs are included, and what features come from where.</span></li> +</ul> +</div> + +<ul> +</ul> diff --git a/files/ko/mdn/guidelines/index.html b/files/ko/mdn/guidelines/index.html new file mode 100644 index 0000000000..d87bfe197c --- /dev/null +++ b/files/ko/mdn/guidelines/index.html @@ -0,0 +1,14 @@ +--- +title: 가이드라인 +slug: MDN/Guidelines +tags: + - MDN 메타 + - 가이드라인 + - 시작하기 +translation_of: MDN/Guidelines +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubNav("/ko/docs/MDN")}}</div> + +<p><span class="seoSummary">이 안내서는 코드 샘플 및 다른 콘텐츠가 보여야 하는 법뿐만 아니라 MDN 문서가 작성되고 형식을 갖추는 법에 대한 세부 정보를 제공합니다.</span> 이 안내서를 따름으로써, 당신의 생산물이 깨끗하고 사용하기 쉽다는 것을 보장할 수 있습니다.</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ko/mdn/guidelines/style_guide/index.html b/files/ko/mdn/guidelines/style_guide/index.html new file mode 100644 index 0000000000..507f30e228 --- /dev/null +++ b/files/ko/mdn/guidelines/style_guide/index.html @@ -0,0 +1,833 @@ +--- +title: MDN 스타일 가이드 +slug: MDN/Guidelines/Style_guide +tags: + - Documentation + - Guide + - MDN + - MDN Meta + - MDN 스타일 가이드 + - 스타일 가이드 + - 스타일 가이드 작성 +translation_of: MDN/Guidelines/Writing_style_guide +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p><span class="seoSummary">정돈되고 일관적이며 읽기 쉬운 문서를 제공하고자, MDN 웹 문서 스타일 안내서는 글의 정렬, 철자, 서식 방법 등을 정리합니다. 이 가이드는 엄격한 규칙이라기보다 가이드라인입니다. 우리는 형식보다는 내용에 더 관심이 있습니다. 그러니 기여하기 전에 스타일 가이드를 배워야 한다는 부담을 느끼시지 않아도 됩니다. 하지만 </span>나중에 다른 부지런한 지원자가 이 가이드를 따라 당신의 작업물을 편집할 수 있습니다. 만약 그런 일이 벌어지더라도 화내거나 놀라지 마세요.</p> + +<p>이 가이드의 언어적 측면의 내용은 영문을 위주로 작성되었습니다. 기타 다른 언어는 언어만의 고유한 스타일 가이드를 가질 수 있으며, 새롭게 만드는 것도 좋습니다. 이 페이지들은 지역화 팀 페이지의 하위 페이지로 생성되어야 합니다.</p> + +<p>MDN이 아닌 다른 사이트를 위해 쓰여진 콘텐츠를 적용하는 스타일 표준에 대한 내용은 <a href="https://www.mozilla.org/en-US/styleguide/">One Mozilla 스타일 가이드</a>를 참고하세요.</p> + +<h2 id="Page_name_and_heading_capitalization" name="Page_name_and_heading_capitalization">기본</h2> + +<p>아무리 방대한 문서화 스타일 가이드라도 가장 기본적인 텍스트 표준에서 시작하는 것이 좋습니다. 텍스트 표준은 일관된 문서화를 유지하는데 도움을 줍니다. 이어지는 섹션에서 도움이 될 만한 이런 기본들을 설명합니다.</p> + +<h3 id="페이지_제목">페이지 제목</h3> + +<p><span id="result_box" lang="ko"><span>페이지 제목은 검색 결과에 사용되며, 페이지 상단의 페이지 이동 경로(breadcrumb) 목록에 페이지 계층 구조를 구성하는 데 사용됩니다.</span> <span> (페이지 상단과 검색 결과 상단</span></span><span lang="ko"><span>에 표시되는) </span></span><span id="result_box" lang="ko"><span>페이지 제목</span></span><span lang="ko"><span>은 페이지 "슬러그"와 다를 수 있습니다. "슬러그"는 페이지 URL의 일부로 "<em><locale>/docs/</em>" 다음에 따라오는 부분입니다.</span></span></p> + +<h4 id="제목과_섹션제목_대문자넣기Capitalization"> 제목과 섹션제목 대문자넣기(Capitalization)</h4> + +<p>페이지 타이틀과 섹션 제목은 헤드라인 스타일 대문자넣기보다는 (첫번째 단어와 필요한 명사만 대문자를 넣는 방식의)일반 문장 스타일 대문자넣기를 해야 합니다:</p> + +<ul> + <li><strong>Correct</strong>: "A new method for creating JavaScript rollovers"</li> + <li><strong>Incorrect</strong>: "A New Method for Creating JavaScript Rollovers"</li> +</ul> + +<p>이런 스타일 규칙이 적용되기 전에 작성된 수많은 예전 문서들이 현재도 존재합니다. 자유롭게 해당 문서들을 수정해도 좋습니다. 우리는 점차적으로 스타일 규칙을 맞춰 나갈겁니다.</p> + +<h4 id="제목_및_슬러그slug_선택하기">제목 및 슬러그(slug) 선택하기</h4> + +<p>페이지 슬러그는 짧게 만들어야 합니다. 새로운 레벨의 계층을 만들때, 그 레벨의 요소는 슬러그에서 한,두 단어로 표현되어야 합니다.</p> + +<p>반면에, 페이지 제목은 ,합리적인 범위내에서, 당신이 원하는 만큼 길어도 됩니다. 그리고 구체적이어야 합니다.</p> + +<h4 id="신규_서브트리_생성하기">신규 서브트리 생성하기</h4> + +<p>어떤 토픽이나 주제 영역에 대한 문서를 추가할 필요가 있다면, 당신이 선택할 일반적인 방법은 랜딩 페이지를 생성한 이후, 각각의 개별적인 문서의 서브페이지를 추가하는 것입니다. 랜딩 페이지는 토픽이나 기술을 설명하는 한두 개의 문단으로 시작한 이후, 각 페이지의 설명이 달린 서브페이지의 목록을 전달해야합니다. 우리가 개발한 몇가지 매크로로 페이지를 목록에 자동으로 삽입할 수 있습니다.</p> + +<p>예를 들면 , 아래와 같이 구성된 <a href="/ko/docs/Web/JavaScript">자바스크립트</a> 가이드를 생각해봅시다.</p> + +<ul> + <li><a href="/ko/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/안내서</a> - 주 목차 페이지</li> + <li><a href="/ko/docs/Web/JavaScript/Guide/소개" title="JavaScript/Guide/JavaScript_Overview">JavaScript/안내서/JavaScript 소</a>개</li> + <li><a href="/ko/docs/Web/JavaScript/Guide/함수" title="JavaScript/Guide/Functions">JavaScript/안내서/함수</a></li> + <li><a href="/ko/docs/Web/JavaScript/Guide/객체_모델의_세부사항" title="JavaScript/Guide/Details_of_the_Object_Model">JavaScript/안내서/객체 모델의 세부사항</a></li> +</ul> + +<p>문서를 문서구조 최상층에 두는 것은 최대한 피해야 합니다. 이렇게 하면 사이트가 느려지며, 사이트 탐색과 네비게이션을 비효율적으로 만듭니다.</p> + +<div class="blockIndicator note"> +<p>주목할 점: 문서 추가는 <a href="https://wiki.developer.mozilla.org/ko/docs/MDN/Contribute/Howto/Create_and_edit_pages#Getting_page-creation_permissions">페이지 생성 권한</a>이 필요합니다.</p> +</div> + +<h3 id="General_article_content_guidelines">General article content guidelines</h3> + +<p>When writing any document, it's important to know how much to say. If you ramble on too long, or provide excessive detail, the article becomes tedious to read and nobody will use it. Getting the amount of coverage right is important for several reasons. Among those reasons: to ensure that the reader finds the information they truly need, and to provide enough quality material for search engines to adequately analyze and rank the article.</p> + +<p>We'll discuss the former (providing the information the reader may need) here. To learn a little about ensuring that pages are properly classified and ranked by search engines, see the article <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_for_SEO">How to write for SEO on MDN</a>.</p> + +<p>The goal is to write pages that include all the information that readers may need without going on too long about it all. We have a few recommendations in this area.</p> + +<h4 id="Consider_your_audience">Consider your audience</h4> + +<p>Keep in mind that these are guidelines. Some of these tips may not apply in every case. Certainly keep your article's audience in mind. An article on advanced network techniques likely doesn't need to go into as much detail about basic networking concepts as the typical article on networking code, for instance.</p> + +<h4 id="Provide_a_useful_summary">Provide a useful summary</h4> + +<p>Make sure the article's summary—that is, the opening paragraph or paragraphs before the first heading—provides enough information for the reader to understand if the article is likely to be covering what they're interested in reading about.</p> + +<p>In guide or tutorial content, the summary should let the reader know what topics will be covered and what they're already expected to know, if anything. It should mention the technology, technologies, and/or APIs that are being documented or discussed, with links to those, and it should offer hints as to the situations in which the article's contents might be useful.</p> + +<h5 id="Example_Too_short!">Example: Too short!</h5> + +<p>This example of a summary is far too short. It leaves out too much information, such as what it means exactly to "stroke" text, where the text is drawn, and so forth.</p> + +<div class="example-bad"><strong><code>CanvasRenderingContext2D.strokeText()</code></strong> draws a string.</div> + +<h5 id="Example_Too_long!">Example: Too long!</h5> + +<p>Here, we've updated the summary, but now it's far too long. Too much detail is included, and the text gets far too much into other methods and properties.</p> + +<p>Instead, the summary should focus on the <code>strokeText()</code> method, and should refer to the appropriate guide where the other details are offered.</p> + +<div class="example-bad"> +<p>When called, the Canvas 2D API method <code><strong>CanvasRenderingContext2D.strokeText()</strong></code> strokes the characters in the specified string beginning at the coordinates specified, using the current pen color.In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.</p> + +<p>The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.</p> + +<p>The placement of the text relative to the specified coordinates are determined by the context's <code>textAlign</code>, <code>textBaseline</code>, and <code>direction</code> properties. <code>textAlign</code> controls the placement of the string relative to the X coordinate specified; if the value is <code>"center"</code>, then the string is drawn starting at <code>x - (stringWidth / 2)</code>, placing the specified X-coordinate in the middle of the string. If the value is <code>"left"</code>, the string is drawn starting at the specified value of <code>x</code>. And if <code>textAlign</code> is <code>"right"</code>, the text is drawn such that it ends at the specified X-coordinate.</p> + +<p>(etc etc etc...)</p> + +<p>You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.</p> + +<p>You can call the <strong><code>fillText()</code></strong> method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.</p> +</div> + +<h5 id="Example_Much_better!">Example: Much better!</h5> + +<p>Here we see a much better overview for the <code>strokeText()</code> method.</p> + +<div class="example-good"> +<p>The {{domxref("CanvasRenderingContext2D")}} method <code><strong>strokeText()</strong></code>, part of the <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/Canvas_API">Canvas 2D API</a>, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.</p> + +<p>For more details and further examples, see {{SectionOnPage("/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text">Drawing text</a>.</p> +</div> + +<h4 id="Include_all_relevant_examples">Include all relevant examples</h4> + +<p>More pages should have examples than not. The majority of pages probably deserve multiple examples, in fact.</p> + +<p>It's important to ensure that you use examples to clarify what every parameter is used for, and to clarify any edge cases that may exist. You should also use examples to demonstrate solutions for common tasks, and you should use examples to demonstrate solutions to problems that may arise.</p> + +<p>Each example should be preceded by text explaining what the example does and anything the reader should know before beginning to read or try out the example.</p> + +<h5 id="Code_Examples">Code Examples</h5> + +<p>Each piece of code should include an explanation of how it works. Keep in mind that it may make sense to break up a large piece of code into smaller portions so they can be described individually.</p> + +<p>The text following each piece of code should explain anything relevant, using an appropriate level of detail.</p> + +<ul> + <li>If the code is very simple and doesn't really feature anything directly related to the API being documented, you may only give a quick summary of what it is and why it's there.</li> + <li>If the code is intricate, uses the API being documented, or is technically creative, you should provide a more detailed explanation.</li> +</ul> + +<p>When using the live sample system, it's helpful to be aware that all of the {{HTMLElement("pre")}} blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible.</p> + +<h4 id="Overly-short_articles_are_hard_to_find">Overly-short articles are hard to find</h4> + +<p>If an article is "thin"—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article's body text should be at least 250–300 words. Don't artificially inflate a page, but treat this guideline as a minimum target length when possible.</p> + +<h3 id="Sections_paragraphs_and_newlines">Sections, paragraphs, and newlines</h3> + +<p>Use heading levels in decreasing order: {{HTMLElement("h2")}} then {{HTMLElement("h3")}} then {{HTMLElement("h4")}}, without skipping levels.</p> + +<p>H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers, consider breaking up the article into several smaller articles with a landing page, and linking them together using the following macros: {{TemplateLink("Next")}}, {{TemplateLink("Previous")}}, and {{TemplateLink("PreviousNext")}}.</p> + +<h4 id="Heading_dos_and_donts">Heading dos and donts</h4> + +<ul> + <li>Don't create single subsections. Don't subdivide a topic into a single subtopic. It's either two subheadings or more, or none at all.</li> + <li>Don't use styles and classes within headings. This includes the {{HTMLElement("code")}} element for code terms. So don't make a heading "Using the <code>SuperAmazingThing</code> interface". It should instead just be "Using the SuperAmazingThing interface".</li> + <li>Avoid using macros within headings (except for certain macros that are specifically designed to be used in headings).</li> + <li>Don't create "bumping heads." These are headings followed immediately by a subheading, with no content text in between. This doesn't look good, and leaves readers without any explanatory text at the beginning of the outer section.</li> +</ul> + +<p>The <kbd>Enter</kbd> (or <kbd>Return</kbd>) key on your keyboard starts a new paragraph. To insert a newline, rather than a new paragraph (that is, to create a {{HTMLElement("br")}} instead of a {{HTMLElement("p")}}), hold down the <kbd>Shift</kbd> key while pressing <kbd>Enter</kbd>.</p> + +<h3 id="Lists">Lists</h3> + +<p>Lists should be formatted and structured uniformly across all contributions. Individual list items should be written with suitable punctuation, regardless of the list format. However, depending on the type of list you are creating, you will want to adjust your writing as described in the sections below.</p> + +<h4 id="Bulleted_lists">Bulleted lists</h4> + +<p>Bulleted lists should be used to group related pieces of concise information. Each item in the list should follow a similar sentence structure. Phrases and sentences in bulleted lists should include standard punctuation. Periods must appear at the end of each sentence in a bulleted list, including the item's final sentence, just as would be expected in a paragraph.</p> + +<p>An example of a correctly structured bulleted list:</p> + +<div class="example-good"> +<p>In this example we should include:</p> + +<ul> + <li>A condition, with a brief explanation.</li> + <li>A similar condition, with a brief explanation.</li> + <li>Yet another condition, with some further explanation.</li> +</ul> +</div> + +<p>Note how the same sentence structure repeats from bullet to bullet. In this example, each bullet point states a condition followed by a comma and a brief explanation, and each item in the list ends with a period.</p> + +<h4 id="Numbered_lists">Numbered lists</h4> + +<p>Numbered lists are used primarily to enumerate steps in a set of instructions. Because instructions can be complex, clarity is a priority, especially if the text in each list item is lengthy. As with bulleted lists, follow standard punctuation usage.</p> + +<p>An example of a correctly structured numbered list:</p> + +<div class="example-good"> +<p>In order to correctly structure a numbered list, you should:</p> + +<ol> + <li>Open with a heading or brief paragraph to introduce the instructions. It's important to provide the user with context before beginning the instructions.</li> + <li>Start creating your instructions, and keep each step in its own numbered item. Your instructions may be quite extensive, so it is important to write clearly and use correct punctuation.</li> + <li>After you have finished your instructions, close off the numbered list with a brief summary or explanation of the expected outcome upon completion.</li> +</ol> + +<p>This is an example of writing a closing explanation. We have created a short numbered list that provides instructive steps to produce a numbered list with the correct formatting.</p> +</div> + +<p>Note how the items in numbered lists read like short paragraphs. Because numbered lists are routinely used for instructional purposes, or to walk someone through an orderly procedure, be sure to keep each item focused: one item per number or step.</p> + +<h3 id="Text_formatting_and_styles">Text formatting and styles</h3> + +<p>Use the <strong>"Formatting Styles"</strong> drop-down list to apply predefined styles to selected content.</p> + +<div class="blockIndicator note"> +<p>The <strong>"Note Box"</strong> style is used to call out important notes, like this one.</p> +</div> + +<div class="blockIndicator warning"> +<p>Similarly, the <strong>"Warning Box"</strong> style creates warning boxes like this.</p> +</div> + +<p>Unless specifically instructed to do so, <em>do not</em> use the HTML <code>style</code> attribute to manually style content. If you can't do it using a predefined class, ask for help in the <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a>.</p> + +<h3 id="Code_sample_style_and_formatting">Code sample style and formatting</h3> + +<div class="blockIndicator note"> +<p><strong>Note</strong>: This section deals with the styling/formatting of code as it appears on an MDN article. If you want guidelines on actually writing code examples, see our <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a>.</p> +</div> + +<h4 id="Tabs_and_line_breaks">Tabs and line breaks</h4> + +<p>Use two spaces per tab in all code examples. Indent the code cleanly, with open-brace ("<code>{</code>") characters on the same line as the statement that opens the block. For example:</p> + +<pre class="notranslate">if (condition) { + /* handle the condition */ +} else { + /* handle the "else" case */ +} +</pre> + +<p>Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:</p> + +<pre class="notranslate">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION + || class.YET_ANOTHER_CONDITION ) { + /* something */ +} + +var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] + .createInstance(Components.interfaces.nsIToolkitProfileService); +</pre> + +<h4 id="Inline_code_formatting">Inline code formatting</h4> + +<p>Use the "Code" button (labeled with two angle brackets "<>") to apply inline code-style formatting to function names, variable names, and method names. (This uses the {{HTMLElement("code")}} element). For example: "the <code>frenchText()</code> function".</p> + +<p>Method names should be followed by a pair of parentheses: <code>doSomethingUseful()</code>. The parentheses help differentiate methods from other code terms.</p> + +<h4 id="Syntax_highlighting">Syntax highlighting</h4> + +<p><img alt="Screenshot of the 'Syntax Highlighter' menu." src="https://mdn.mozillademos.org/files/12682/Language%20list.png" style="float: right;">Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the {{HTMLElement("code")}} element. Select the appropriate language from the language list button (the one with the two code blocks), as seen in the screenshot to the right. This will insert a preformatted code box with line numbers and syntax highlighting for the chosen language.</p> + +<div class="blockIndicator note"> +<p><strong>Note:</strong> <em>Do not</em> use the {{HTMLElement("code")}} element inside the {{HTMLElement("pre")}} block!</p> + +<p>While this structure is used on some sites, we do not do so on MDN; nesting these elements will break certain aspects of our styling.</p> +</div> + +<p>The following example shows text with JavaScript formatting:</p> + +<pre class="notranslate">for (let i = 0, j = 9; i <= 9; i++, j--) + document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre> + +<p>If no appropriate language is available, use ("No Highlight" in the language menu). This will result in code without syntax highlighting:</p> + +<pre class="notranslate">x = 42;</pre> + +<h4 id="Syntax_definitions">Syntax definitions</h4> + +<p>When writing the syntax description section of a reference page, use the <em>"Syntax Box"</em> option in the <strong>"Styles"</strong> drop-down menu in the editor toolbar. This creates a specially-formatted box used specifically for syntax definitions, distinguishing them from other code blocks.</p> + +<h4 id="Blocks_not_referring_to_code">Blocks not referring to code</h4> + +<p>There are a few use cases where a <code><pre></code> block does not refer to code and doesn't have syntax highlighting nor line numbers. In such cases you should add a <code><pre></code> without a <code>class</code> attribute. Those cases include things like tree structures:</p> + +<pre class="notranslate">root/ + + folder1/ + file1 + + folder2/ + file2 + file3 +</pre> + +<p>To create preformatted content without syntax highlighting and line numbers click the "pre" button in the toolbar. Then start to type the text.</p> + +<h4 id="Styling_mentions_of_HTML_elements">Styling mentions of HTML elements</h4> + +<p>There are specific rules to follow when writing about HTML elements. These rules produce consistent descriptions of elements and their components. They also ensure correct linking to detailed documentation.</p> + +<dl> + <dt>Element names</dt> + <dd>Use the {{TemplateLink("HTMLElement")}} macro, which creates a link to the page for that element. For example, writing \{{HTMLElement("title")}} produces "{{HTMLElement("title")}}". If you don't want to create a link, <strong>enclose the name in angle brackets</strong> and use the "Inline Code" style (e.g., <code><title></code>).</dd> + <dt>Attribute names</dt> + <dd>Use "Inline Code" style to put attribute names in <code>code font</code>. Additionally, put them in <strong><code>bold face</code></strong> when the attribute is mentioned in association with an explanation of what it does, or the first time it's used in the article.</dd> + <dt>Attribute definitions</dt> + <dd>Use the {{TemplateLink("htmlattrdef")}} macro (e.g., \{{htmlattrdef("type")}}) for the definition term, so that it can be linked to from other pages easily by simply using the {{TemplateLink("htmlattrxref")}} macro (e.g., \{{htmlattrxref("attr","element")}}) to reference attribute definitions.</dd> + <dt>Attribute values</dt> + <dd>Use the "Inline Code" style to apply <code><code></code> to attribute values, and don't use quotation marks around string values, unless needed by the syntax of a code sample.</dd> + <dd>For example: "When the <code>type</code> attribute of an <code><input></code> element is set to <code>email</code> or <code>tel</code> ..."</dd> +</dl> + +<h3 id="Latin_abbreviations">Latin abbreviations</h3> + +<h4 id="In_notes_and_parentheses">In notes and parentheses</h4> + +<ul> + <li>Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and notes. Use periods in these abbreviations, followed by a comma or other appropriate punctuation. + <ul> + <li><span class="correct"><strong>Correct</strong></span>: Web browsers (e.g., Firefox) can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, e.g. Firefox, can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, (eg: Firefox) can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="In_running_text">In running text</h4> + +<ul> + <li>In regular text (i.e., text outside of notes or parentheses), use the English equivalent of the abbreviation. + <ul> + <li><span class="correct"><strong>Correct</strong></span>: ... web browsers, and so on.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: ... web browsers, etc.</li> + <li><span class="correct"><strong>Correct</strong></span>: Web browsers such as Firefox can be used ...</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations">Meanings and English equivalents of Latin abbreviations</h4> + +<table> + <thead> + <tr> + <th scope="col">Abbrev</th> + <th scope="col">Latin</th> + <th scope="col">English</th> + </tr> + </thead> + <tbody> + <tr> + <td>cf.</td> + <td><em>confer</em></td> + <td>compare</td> + </tr> + <tr> + <td>e.g.</td> + <td><em>exempli gratia</em></td> + <td>for example</td> + </tr> + <tr> + <td>et al.</td> + <td><em>et alii</em></td> + <td>and others</td> + </tr> + <tr> + <td>etc.</td> + <td><em>et cetera</em></td> + <td>and so forth, and so on</td> + </tr> + <tr> + <td>i.e.</td> + <td><em>id est</em></td> + <td>that is, in other words</td> + </tr> + <tr> + <td>N.B.</td> + <td><em>nota bene</em></td> + <td>note well</td> + </tr> + <tr> + <td>P.S.</td> + <td><em>post scriptum</em></td> + <td>postscript</td> + </tr> + </tbody> +</table> + +<div class="blockIndicator note"> +<p>Always consider whether it's truly beneficial to use a Latin abbreviation. Some of these are used so rarely that many readers won't understand the meaning, and others are often confused with one another.</p> + +<p>Also, be sure that <em>you</em> use them correctly, if you choose to do so. For example, be careful not to confuse "e.g." with "i.e.", which is a common error.</p> +</div> + +<h3 id="Acronyms_and_abbreviations">Acronyms and abbreviations</h3> + +<h4 id="Capitalization_and_periods">Capitalization and periods</h4> + +<p>Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".</p> + +<ul> + <li><strong>Correct</strong>: XUL</li> + <li><strong>Incorrect</strong>: X.U.L.; Xul</li> +</ul> + +<h4 id="Expansion">Expansion</h4> + +<p>On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article or <a href="https://wiki.developer.mozilla.org/en-US/docs/Glossary">glossary</a> entry describing the technology.</p> + +<ul> + <li><strong>Correct</strong>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."</li> + <li><strong>Incorrect</strong>: "XUL is Mozilla's XML-based language..."</li> +</ul> + +<h4 id="Plurals_of_acronyms_and_abbreviations">Plurals of acronyms and abbreviations</h4> + +<p>For plurals of acronyms or abbreviations, add <em>s</em>. Don't use an apostrophe. Ever. Please.</p> + +<ul> + <li><strong>Correct</strong>: CD-ROMs</li> + <li><strong>Incorrect</strong>: CD-ROM's</li> +</ul> + +<h4 id="Versus_vs._and_v.">"Versus", "vs.", and "v."</h4> + +<p>The contraction "vs." is preferred.</p> + +<ul> + <li><strong>Correct</strong>: this vs. that</li> + <li><strong>Incorrect</strong>: this v. that</li> + <li><strong>Incorrect</strong>: this versus that</li> +</ul> + +<h3 id="Capitalization">Capitalization</h3> + +<p>Use standard English capitalization rules in body text, and capitalize "World Wide Web." It is acceptable to use lower case for "web" (used alone or as a modifier) and "internet".</p> + +<div class="blockIndicator note"> +<p>This guideline is a change from a previous version of this guide, so you may find many instances of "Web" and "Internet" on MDN.</p> + +<p>Feel free to change these as you are making other changes, but editing an article just to change capitalization is not necessary.</p> +</div> + +<p>Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "<kbd>Enter</kbd>" not "<kbd>ENTER</kbd>." The only exception is that if you wish to abbreviate the name of the "<kbd>Escape</kbd>" key, you may use "<kbd>ESC</kbd>".</p> + +<p>Certain words should always be capitalized (such as trademarks which include capital letters), or words derived from the name of a person (unless it's being used within code, and the rules of the language in which the code is written mandate lower-casing). Some examples:</p> + +<ul> + <li>Boolean (named for English mathematician and logician {{interwiki("wikipedia", "George Boole")}})</li> + <li>JavaScript (a trademark of Oracle Corporation, it should always be written as trademarked)</li> + <li>Python, TypeScript, Django, and other programming languages and framework names</li> +</ul> + +<h3 id="Contractions">Contractions</h3> + +<p>Our writing style tends to be casual, so you should feel free to use contractions (e.g., "don't", "can't", "shouldn't"), if you prefer.</p> + +<h3 id="Pluralization">Pluralization</h3> + +<p>Use English-style plurals, not the Latin- or Greek-influenced forms.</p> + +<ul> + <li><strong>Correct</strong>: syllabuses, octopuses</li> + <li><strong>Incorrect</strong>: syllabi, octopi</li> +</ul> + +<h3 id="Hyphenation">Hyphenation</h3> + +<p>Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.</p> + +<ul> + <li><font color="green"><strong>Correct</strong></font>: email, re-elect, co-op</li> + <li><font color="red"><strong>Incorrect</strong></font>: e-mail, reelect, coop</li> +</ul> + +<h3 id="Gender-neutral_language">Gender-neutral language</h3> + +<p>It is a good idea to use gender-neutral language in any writing where gender is irrelevant to the subject matter, to make the text as inclusive as possible. So, for example, if you are talking about the actions of a specific man, usage of "he"/"his" is fine; but if the subject is a person of either gender, "he"/"his" isn't appropriate.<br> + <br> + Let's take the following example:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he allows the Web page to make use of his Web cam.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog appears, asking the user if she allows the Web page to make use of her Web cam.</p> +</blockquote> + +<p>Both versions are gender-specific. To fix this, use gender-neutral pronouns:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.</p> +</blockquote> + +<div class="blockIndicator note"> +<p>MDN allows the use of this very common syntax (which is controversial among usage authorities) to make up for the lack of a neutral gender in English.</p> + +<p>The use of the third-person plural as a gender neutral pronoun (that is, using "they," "them", "their," and "theirs") is an accepted practice, commonly known as "<a href="https://en.wikipedia.org/wiki/Singular_they">singular 'they.'</a>"</p> +</div> + +<p>You can use both genders:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.</p> +</blockquote> + +<p>Making the users plural:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.</p> +</blockquote> + +<p>The best solution, of course, is to rewrite and eliminate the pronouns:</p> + +<blockquote> +<p>A confirmation dialog appears, requesting the user's permission for web cam access.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog box appears, which asks the user for permission to use the web cam.</p> +</blockquote> + +<p>The last way of dealing with the problem is arguably better. It is not only grammatically more correct, but removes some of the complexity associated with dealing with genders across different languages that may have wildly different gender rules. This solution can make translation easier for both readers and localizers.</p> + +<h3 id="Numbers_and_numerals">Numbers and numerals</h3> + +<h4 id="Dates">Dates</h4> + +<p>For dates (not including dates in code samples) use the format "January 1, 1990".</p> + +<ul> + <li><strong>Correct</strong>: February 24, 2006</li> + <li><strong>Incorrect</strong>: February 24th, 2006; 24 February, 2006; 24/02/2006</li> +</ul> + +<p>Alternately, you can use the YYYY/MM/DD format.</p> + +<ul> + <li><strong>Correct</strong>: 2006/02/24</li> + <li><strong>Incorrect</strong>: 02/24/2006; 24/02/2006; 02/24/06</li> +</ul> + +<h4 id="Decades">Decades</h4> + +<p>For decades, use the format "1990s". Don't use an apostrophe.</p> + +<ul> + <li><strong>Correct</strong>: 1990s</li> + <li><strong>Incorrect</strong>: 1990's</li> +</ul> + +<h4 id="Plurals_of_numerals">Plurals of numerals</h4> + +<p>For plurals of numerals add "s". Don't use an apostrophe.</p> + +<ul> + <li><strong>Correct</strong>: 486s</li> + <li><strong>Incorrect</strong>: 486's</li> +</ul> + +<h4 id="Commas">Commas</h4> + +<p>In running text, use commas only in five-digit and larger numbers.</p> + +<ul> + <li><strong>Correct</strong>: 4000; 54,000</li> + <li><strong>Incorrect</strong>: 4,000; 54000</li> +</ul> + +<h3 id="Punctuation">Punctuation</h3> + +<h4 id="Serial_comma">Serial comma</h4> + +<p><strong>Use the serial comma</strong>. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.</p> + +<ul> + <li><strong>Correct</strong>: I will travel on trains, planes, and automobiles.</li> + <li><strong>Incorrect</strong>: I will travel on trains, planes and automobiles.</li> +</ul> + +<div class="blockIndicator note"> +<p>This is in contrast to the <a href="https://www.mozilla.org/en-US/styleguide/" title="https://www.mozilla.org/en-US/styleguide/">One Mozilla style guide</a>, which specifies that the serial comma is not to be used. MDN is an exception to this rule.</p> +</div> + +<h4 id="Apostrophes_and_quotation_marks">Apostrophes and quotation marks</h4> + +<p><strong>Do not use "curly" quotes and quotation marks.</strong> On MDN, we only use straight quotes and apostrophes.</p> + +<p>There are a couple of reasons for this.</p> + +<ol> + <li>We need to choose one or the other for consistency.</li> + <li>If curly quotes or apostrophes make their way into code snippets—even inline ones—readers may copy and paste them, expecting them to function (which they will not).</li> +</ol> + +<ul> + <li><strong>Correct</strong>: Please don't use "curly quotes."</li> + <li><strong>Incorrect</strong>: Please don’t use “curly quotes.”</li> +</ul> + +<h3 id="Spelling">Spelling</h3> + +<p>For words with variant spellings, always use their American English spelling.</p> + +<p>In general, use the first entry at <a href="http://www.dictionary.com/">Dictionary.com</a>, unless that entry is listed as a variant spelling or as being primarily used in a non-American form of English. For example, if you <a href="http://www.dictionary.com/browse/behaviour">look up "behaviour"</a>, you find the phrase "Chiefly British" followed by a link to the American standard form, "<a href="http://dictionary.reference.com/browse/behavior">behavior</a>". Do not use variant spellings.</p> + +<ul> + <li><strong>Correct</strong>: localize, behavior</li> + <li><strong>Incorrect</strong>: localise, behaviour</li> +</ul> + +<h3 id="Terminology">Terminology</h3> + +<h4 id="HTML_elements">HTML elements</h4> + +<p>Use "elements" to refer to HTML and XML elements, rather than "tags". In addition, they should almost always be wrapped in "<>", and should be in the {{HTMLElement("code")}} style.</p> + +<p>When you reference a given element for the first time in a section, you should use the {{TemplateLink("HTMLElement")}} macro to create a link to the documentation for the element (unless you're writing within that element's reference document page).</p> + +<ul> + <li><strong>Correct</strong>: the {{HTMLElement("span")}} element</li> + <li><strong>Incorrect</strong>: the span tag</li> +</ul> + +<h4 id="Parameters_vs._arguments">Parameters vs. arguments</h4> + +<p>The preferred term on MDN is <strong>parameters</strong>. Please avoid the term "arguments" for consistency whenever possible.</p> + +<h4 id="User_interface_actions">User interface actions</h4> + +<p>In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.</p> + +<ul> + <li><strong>Correct</strong>: Click the Edit button.</li> + <li><strong>Incorrect</strong>: Click Edit.</li> +</ul> + +<h3 id="Voice">Voice</h3> + +<p>While the active voice is preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.</p> + +<h2 id="위키_마크업과_사용법">위키 마크업과 사용법</h2> + +<h3 id="링크">링크</h3> + +<p>링크는 위키를 강력한 배움과 가르침의 도구로 만드는 데 큰 역할을 합니다. 아래에서 관련한 기본적 정보를 찾을 수 있지만, 에디터 가이드에 있는 <a href="https://wiki.developer.mozilla.org/ko/docs/MDN/Contribute/Editor/Links">MDN에서 링크를 생성하고 편집하기</a> 에서는 완전한 가이드를 볼 수 있습니다.</p> + +<p>우리는 당신이 문서간에 적절한 링크를 생성하도록 권장합니다; 링크는 콘덴츠 검색 용이성및 네비게이션을 개선하는데 도움을 주고, 구글과 같은 검색 엔진이 더 나은 검색결과를 제공하도록 중요한 콘텍스트를 제공 합니다. 모든 페이지는 단어나 구문에서 관련된 주제의 다른 페이지로 연결되는 좋은 링크집합을 가져야 합니다. 링크는 용어를 정의하거나 어떤 주제에 대한 상세하고 심화된 문서를 제공하는데에 모두 사용될 뿐만 아니라, 관련된 예제나 보다 관심이 갈만한 정보도 제공할 수도 있습니다.</p> + +<p>MDN내부의 문서(내부 링크)뿐만아니라 MDN 외부의 페이지(외부 링크)도 쉽게 링크를 걸 수 있습니다 .</p> + +<p>링크를 만드는 두 가지 방법이 있습니다:</p> + +<ul> + <li>에디터 툴바내의 링크 버튼을 이용하거나 <kbd>Ctrl</kbd>+<kbd>K</kbd> (맥에서는 <kbd>Cmd</kbd>+<kbd>K</kbd>)를 눌러서 명시적으로 링크를 성성합니다.</li> + <li>또는, MDN의 강력한 매크로 시스템을 이용하여 자동적으로 혹은 입력값 기반으로 링크를 생성할 수 있습니다.</li> +</ul> + +<p>어떤 텍스트에 링크를 연결할 것인지에 대해, 몇가지 가이드라인을 소개합니다:</p> + +<ul> + <li><strong>필요한 링크를 생성할 매크로가 존재하는 모든 경우에, 매크로를 이용해도 됩니다. 꼭 이용해주세요.</strong> <a href="https://wiki.developer.mozilla.org/ko/docs/MDN/Contribute/Editor/Links#Using_link_macros">링크 생성에 매크로 사용하기</a> 는 올바로 링크를 생성하도록 도울 뿐만 아니라, 미래에 MDN에 이루어질 개선이 당신의 링크에 자동적으로 적용되도록 합니다. .</li> + <li><strong>API 이름에 대해서는, 문서에 쓰인 API 용어의 전체 문자열을 사용하세요.</strong> 가장 쉬운 방법은 당신에게 맞는 올바른 형식을 갖춘 링크를 구성하기에 <a href="https://wiki.developer.mozilla.org/ko/docs/MDN/Contribute/Editor/Links#Linking_to_documentation_for_APIs">적절한 매크로를 사용하는 것</a> 이다.</li> + <li>특정한 용어에 대해 논하거나 정의하는 페이지에 링크하기 위해, 링크 문자열에 용어의 이름만을 사용하세요; 그외의 추가적인 텍스트를 포함하지 마세요. 예를 들면: + <ul> + <li><span class="correct"><strong>바름</strong></span>: You can use <a href="https://wiki.developer.mozilla.org/ko/docs/Web/JavaScript">JavaScript</a> code to create dynamic applications on the Web.</li> + <li><span class="incorrect"><strong>틀림</strong></span>: You can use <a href="https://wiki.developer.mozilla.org/ko/docs/Web/JavaScript">JavaScript code</a> to create dynamic applications on the Web.</li> + </ul> + </li> + <li>반면에 , 약간 긴 문장에 유용한 링크를 추가할 때에는, 다음과 같이, 동작과 목적어만 포함하는 구문을 선택하도록 해보세요: + <ul> + <li><span class="correct"><strong>바름</strong></span>: If you'd like to <a href="https://wiki.developer.mozilla.org/ko/docs/Mozilla/Developer_guide">contribute to the Firefox project</a>, your first step is to <a href="https://wiki.developer.mozilla.org/ko/docs/Mozilla/Developer_guide/Build_Instructions">download and build Firefox</a>.</li> + <li><span class="incorrect"><strong>틀림</strong></span>: <a href="https://wiki.developer.mozilla.org/ko/docs/Mozilla/Developer_guide">If you'd like to contribute to the Firefox project</a>, your first step is to <a href="https://wiki.developer.mozilla.org/ko/docs/Mozilla/Developer_guide/Build_Instructions">download and build</a> Firefox.</li> + </ul> + </li> +</ul> + +<h4 id="URL_정책">URL 정책</h4> + +<p>보안 때문에, 아래 스킴(schemes)을 사용한 링크만 생성할 수 있다:</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>이 외의 것은 동작할 수도 아닐수도 있지만, 편집 스태프에 의해 지원되거나 삭제되지 않을 것이다.</p> + +<div class="blockIndicator note"> +<p>특별히, <code>about:</code> 이나 <code>chrome://</code> 스킴은 동작하지 않으므로 피해야 한다.</p> + +<p>유사하게 , <code>javascript:</code> 스킴도 <code>jar:</code>와 마찬가지로 대부분의 모던 브라우저에서 막혀있다</p> +</div> + +<h3 id="페이지_태그">페이지 태그</h3> + +<p>Tags provide meta information about a page and/or indicate that a page has specific improvements needed to its content. Every page in the wiki should have tags.</p> + +<p>You can find details on tagging in our <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> guide.</p> + +<p>The tagging interface lives at the bottom of a page while you're in edit mode, and looks something like this:</p> + +<p><img alt="Screenshot of the UX for adding and removing tags on MDN" src="https://mdn.mozillademos.org/files/7859/tag-interface.png"></p> + +<p>To add a tag, click in the edit box at the end of the tag list and type the tag name you wish to add. Tags will autocomplete as you type. Press <kbd>Enter</kbd> (or <kbd>Return</kbd>) to submit the new tag. Each article may have as many tags as needed. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.</p> + +<p>To remove a tag, just click the little "<code>×</code>" icon in the tag.</p> + +<h4 id="Tagging_pages_that_need_work">Tagging pages that need work</h4> + +<p>In addition to using tags to track information about the documentation's quality and content, we also use them to mark articles as needing specific types of work.</p> + +<h4 id="Tagging_obsolete_pages">Tagging obsolete pages</h4> + +<p>Use the following tags for pages that are not current:</p> + +<dl> + <dt>Junk</dt> + <dd>Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.</dd> + <dt>Obsolete</dt> + <dd> + <p>Use for content that is technically superseded, but still valid in context. For example, this might be an HTML element that is obsolete in HTML5, but still valid in HTML 4.01.</p> + + <p>You can also use the {{TemplateLink("obsolete_header")}} macro to put a prominent banner on the topic.</p> + </dd> + <dt>Archive</dt> + <dd> + <p>Use for content that is technically superseded and no longer useful. If possible, add a note to the topic referring readers to a more current topic.</p> + + <p>For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the <em>NeedsUpdate</em> tag, and add an explanation on the Talk page.)</p> + + <p>Pages with the <em>Archive</em> tag are eventually moved from the main content of MDN to the <a href="https://wiki.developer.mozilla.org/en-US/docs/Archive">Archive</a> section.</p> + </dd> +</dl> + +<h3 id="SEO_summary">SEO summary</h3> + +<p>The SEO summary provides a short description of a page. It will be reported as a summary of the article to robots crawling the site, and will then appear in search results for the page. It is also used by macros that automate the construction of landing pages inside MDN itself. (In other words, it's not just for SEO.)</p> + +<p>By default, the first paragraph of the page is used as the SEO summary. However, you can override this behavior by marking a section with the <a href="https://wiki.developer.mozilla.org/en-US/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles">"SEO summary" style in the WYSIWYG editor</a>.</p> + +<h3 id="Landing_pages">Landing pages</h3> + +<p><strong>Landing pages</strong> are pages at the root of a topic area of the site, such as the main <a href="https://wiki.developer.mozilla.org/en-US/docs/CSS" title="CSS">CSS</a> or <a href="https://wiki.developer.mozilla.org/en-US/docs/HTML" title="HTML">HTML</a> pages. They have a standard format that consists of three areas:</p> + +<ol> + <li>A brief (typically one paragraph) overview of what the technology is and how it's used. See {{anch("Writing a landing page overview")}} for tips.</li> + <li>A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.</li> + <li>An <strong>optional</strong> "Browser compatibility" section at the bottom of the page.</li> +</ol> + +<h4 id="Creating_a_page_link_list">Creating a page link list</h4> + +<p>The link list section of an MDN landing page consists of two columns. These are created using the following HTML:</p> + +<pre class="notranslate"><div class="row topicpage-table"> + <div class="section"> + ... left column contents ... + </div> + <div class="section"> + ... right column contents ... + </div> +</div></pre> + +<p>The left column should be a list of articles, with an <code><h2></code> header at the top of the left column explaining that it's a list of articles about the topic (e.g., "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <code><dl></code> list of articles with each article's link in a <code><dt></code> block and a brief one-or-two sentence summary of the article in the corresponding <code><dd></code> block.</p> + +<p>The right column should contain one or more of the following sections, in order:</p> + +<dl> + <dt>Getting help from the community</dt> + <dd>This should provide information on Matrix chat rooms and mailing lists available on the topic. The heading should use the class "Community".</dd> + <dt>Tools</dt> + <dd>A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".</dd> + <dt>Related topics</dt> + <dd>A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".</dd> +</dl> + +<p><strong>{{TODO("Finish this once we finalize the landing page standards")}}</strong></p> + +<h2 id="Using_and_inserting_images">Using and inserting images</h2> + +<p>It's sometimes helpful to provide an image in an article you create or modify, especially if the article is very technical.</p> + +<p>To include an image:</p> + +<ol> + <li>Before uploading your image, please ensure that it's as small as possible by using an image optiization tool. + <ul> + <li>For bitmap images (JPG or PNG), consider a tool such as <a href="https://imageoptim.com/mac">ImageOptim</a> (macOS), <a href="https://tinypng.com/">TinyPNG</a> (web service), or <a href="https://trimage.org/">Trimage</a> (Linux).</li> + <li>For SVG images, use the <code><a href="https://github.com/svg/svgo">svgo</a></code> tool to optimize the SVG file before sending it. The default configuration is fine.</li> + </ul> + </li> + <li>Attach the desired image file to the article (at the bottom of every article in edit mode). If your artwork is a diagram in SVG format (which is ideal if there is text that may need to be localized), you can't upload it directly, but you can ask an MDN admin to do it for you.</li> + <li>Click the "<strong>insert image</strong>" button in the MDN documentation WYSIWYG editor.</li> + <li>In the WYSIWYG editor's drop-down list of attachments, select the newly created attachment that is your image.</li> + <li>Press the <strong>OK</strong> button.</li> +</ol> + +<div class="blockIndicator warning"> +<p><strong>Important:</strong> Remember to save any changes you've made before uploading an attachment to your article! The editor is closed during the upload process, and currently <em>does not verify</em> whether or not you wish to save your work when it does so.</p> +</div> + +<h2 id="Other_references">Other references</h2> + +<h3 id="Preferred_style_guides">Preferred style guides</h3> + +<p>If you have questions about usage and style not covered here, we recommend referring to the <a href="https://docs.microsoft.com/en-us/style-guide/welcome/">Microsoft Writing Style Guide</a>—or, failing that, the <a href="https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206">Chicago Manual of Style</a>. An <a href="https://faculty.cascadia.edu/cma/HIST148/cmscrib.pdf">unofficial crib sheet for the Chicago Manual of Style</a> is available online.</p> + +<h3 id="Preferred_dictionary">Preferred dictionary</h3> + +<p>For questions of spelling, please refer to <a href="http://www.dictionary.com/">Dictionary.com</a>. The spelling checker for this site uses American English. Please do not use variant spellings (e.g., use <em>color</em> rather than <em>colour</em>).</p> + +<p>We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please post them on the <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a>, so we know what should be added.</p> + +<h3 id="MDN-specific">MDN-specific</h3> + +<ul> + <li><a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="Project:en/Custom_Templates">Commonly-used macros</a> on MDN, with explanations</li> +</ul> + +<h3 id="Language_grammar_spelling">Language, grammar, spelling</h3> + +<p>If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.</p> + +<ul> + <li><a href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li> + <li><a href="http://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/" title="http://www.amazon.com/Style-Lessons-Clarity-Grace-Edition/dp/0321898680">Style: The Basics of Clarity and Grace</a>, by Joseph Williams and Gregory Colomb (Amazon link)</li> + <li><a href="https://brians.wsu.edu/common-errors-in-english-usage/">Common Errors in English</a></li> + <li><a href="http://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li> + <li><a href="http://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li> + <li><a href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2" title="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li> + <li><a href="http://english.stackexchange.com/">English Language and Usage StackExchange</a>: Question and answer site for English language usage.</li> +</ul> diff --git a/files/ko/mdn/index.html b/files/ko/mdn/index.html new file mode 100644 index 0000000000..283278498e --- /dev/null +++ b/files/ko/mdn/index.html @@ -0,0 +1,34 @@ +--- +title: MDN 프로젝트 +slug: MDN +tags: + - Documentation + - MDN + - NeedsTranslation + - TopicStub +translation_of: MDN +--- +<div>{{MDNSidebar}}</div> + +<p><strong>Mozilla Developer Network</strong>(MDN)는 오픈 웹, Mozilla 기술, Firefox OS를 비롯한 개발을 주제로 한 문서를 보관하는 위키입니다. 이곳에는 누구나 내용을 추가하거나 편집할 수 있습니다. 프로그래머가 아니거나 기술에 대해 많이 알고 있지 않아도 괜찮습니다. 글이 잘 읽히도록 문장을 다듬고 오타를 교정하는 간단한 일부터, API 문서를 작성하는 일까지 해야하는 일은 다양하니까요.</p> + +<div class="summary"> +<p>MDN 프로젝트는 오픈 웹, Mozilla 기술, Mozilla 프로젝트 문서화를 목표로 합니다. 여러분들께 도움을 청합니다!</p> +</div> + +<p>여러분들의 도움이 필요합니다! 글을 쓰고 수정하는데 권한이 필요한 건 아닌지 실수를 하면 어떻게 될지 두려워하지 마세요. 대신 <a href="/ko/docs/MDN/Community" title="/ko/docs/MDN/Community">MDN 공동체</a>에 대해 한번 알아보세요. 우리는 여러분을 도와드리기 위해 이곳에 있습니다! 아래의 문서들을 통해 MDN에 참여하는 법을 배울 수 있습니다.</p> + + + +<ul class="card-grid"> + <li><span><a href="/ko/docs/MDN/Getting_started">초보자 가이드</a></span> + + <p>MDN이 처음이고 문서 개선에 참여하고 싶으신가요? 여기서부터 시작하세요!</p> + </li> + <li><span><a href="/ko/docs/MDN/Contribute">숙련자 가이드</a></span> + <p>MDN 기여자를 위한 완벽하고 깊이있는 가이드 문서가 준비되어 있습니다.</p> + </li> + <li><span><a class="new" href="/ko/docs/MDN/Promote" rel="nofollow">MDN 알리기</a></span> + <p>MDN이 마음에 드신다면 세상에 알려주세요! MDN을 알리는데 필요한 그림, 도구, 안내문을 찾아보세요.</p> + </li> +</ul> diff --git a/files/ko/mdn/kuma/index.html b/files/ko/mdn/kuma/index.html new file mode 100644 index 0000000000..becf84221a --- /dev/null +++ b/files/ko/mdn/kuma/index.html @@ -0,0 +1,26 @@ +--- +title: '쿠마(Kuma): MDN 위키 플랫폼' +slug: MDN/Kuma +tags: + - MDN 메타 + - 시작하기 + - 쿠마 +translation_of: MDN/Kuma +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<div>쿠마(Kuma)는 MDN Web Docs를 작동시키는 Django 코드 입니다. </div> + +<p>{{SubpagesWithSummaries}}</p> + +<h2 id="Kuma와_함께해주세요.">Kuma와 함께해주세요. </h2> + +<p>함께 하고 싶다면 </p> + +<ul> + <li><a href="https://github.com/mozilla/kuma">Github의 Kuma 프로젝트</a>를 방문해서 </li> + <li><a href="https://github.com/mozilla/kuma/blob/master/CONTRIBUTING.md">기여하는 법</a>을 확인하고 </li> + <li>필요하다면 <a href="http://kuma.readthedocs.org/en/latest/">kuma 문서 전체</a>를 차근차근 살펴보세요. </li> +</ul> diff --git a/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html b/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html new file mode 100644 index 0000000000..fd8be5585d --- /dev/null +++ b/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html @@ -0,0 +1,114 @@ +--- +title: API 레퍼런스의 사이드바 +slug: MDN/Structures/API_references/API_reference_sidebars +translation_of: MDN/Structures/API_references/API_reference_sidebars +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">API 레퍼런스 문서에는 수정 가능한 사이드바 를 추가할 수 있습니다. 이 사이드바에 인터페이스, 튜토리얼, 혹은 API와 관련된 자료 링크를 노출합니다. 그 사용법을 설명합니다. </p> + +<h2 id="뭘_해야_하나요">뭘 해야 하나요?</h2> + +<p>사이드바 생성은 다음 세 단계로 나뉩니다. </p> + +<ol> + <li>API 레퍼런스 페이지를 만듭니다. </li> + <li><a href="https://github.com/mdn/kumascript">KumaScript 레파지토리</a>의 GroupData.json 데이터 파일에 그 API를 위한 엔트리를 추가합니다. </li> + <li>사이드바가 필요한 페이지에 \{{APIRef}} 메크로를 추가합니다.</li> +</ol> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>를 샘플로 삼아서 단계별로 살펴 보겠습니다. </p> + +<h3 id="신규_API_레퍼런스_페이지_만들기">신규 API 레퍼런스 페이지 만들기</h3> + +<p>페이지에 사이드바를 추가하기 전에 여러분은 페이지를 만들어야 합니다. (자세한건 API 레퍼런스 문서에 필요한건 무엇일까요? 마이드 문서를 보세요)</p> + +<h3 id="GroupData.json에_API의_엔트리를_추가하기">GroupData.json에 API의 엔트리를 추가하기</h3> + +<p><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> 파일은 API 레퍼런스 문서의 사이드바 안에 담아야 하는 모든 데이타를 담고 있습니다. API를 파라미터로 주고 \{{APIRef}}메크로를 실행하면, GroupData.json에서 탐색해서 사이드바를 생성하고 페이지에 추가합니다. </p> + +<p>GroupData.json에 엔트리를 추가하려면 다음을 따르세요.</p> + +<ol> + <li><a href="https://github.com/">GitHub</a> 계정이 필요합니다. </li> + <li>KumaScript 레파지토리를 포크뜨고, 작업할 브랜치를 생성하고 로컬에 클론을 뜹니다. </li> + <li>생성한 브랜치로 체크아웃을 하고 작업후 오리진으로 푸시합니다. </li> + <li>MDN 팀이 리뷰할 수 있도록 풀 리퀘스트를 날려주시고, 필요하다 생각이 들면 변경 요청을 주세요.</li> +</ol> + +<p>GitHub 사용법을 잘 모르겠으면 <a href="/ko/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">호환성 테이블 가이드</a> 문서를 참고하세요. 자세한 내용이 있습니다. </p> + +<p><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a>은 KumaScript 레파지토리의 macros 폴더 안에 있습니다. 파일을 열어보면 API별로 자기 내용을 가진 거대한 JSON 구조체를 볼 수 있습니다. 키는 API명이고, 값은 사이드바 링크를 생성하기 위해 정의된 하위 멤버를 담은 객체입니다. </p> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> 를 예로 들면 일치하는 GroupData.json의 엔트리가 다음과 같습니다. </p> + +<pre class="brush: json notranslate">"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Body", + "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "WindowOrWorkerGlobalScope.fetch()" ], + "properties": [], + "events": [] +}, +</pre> + +<p>보다시피 키 명을 "Fetch API"으로 명명 하고 있고, 하위 멤버들을 담은 객체를 가지고 있습니다. </p> + +<h4 id="GroupData_엔트리에_담긴_하위_멤버들">GroupData 엔트리에 담긴 하위 멤버들</h4> + +<p>GroupData 엔트리에 추가할 수 있는 하위 멤버 목록입니다. </p> + +<p>리스트업된 하위 멤버값 대부분은 링크걸 텍스트와 링크 생성을 위해 메인 API 색인 페이지(https://developer.mozilla.org/<em><language-code></em>/docs/Web/API) 끝에 추가될 슬러그입니다. 예를 들어 en-US 로케일에서 "Body"는 아래 링크를 만듭니다. </p> + +<pre class="brush: html notranslate"><li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li> +</pre> + +<p>몇가지 예외가 있습니다.. 예를 들어 "guides" 하위 멤버는 가이드/튜토리얼 관련 링크를 정의할 하나이상의 링크 정보(타이틀과 슬러그)를 갖고 있는데, 이경우 슬러그는 MDN 어디든 추가될 수 있도록 MDN 문서 루트(https://developer.mozilla.org/<em><language-code></em>/docs)의 끝에 추가됩니다. </p> + +<p>사용가능한 멤버들입니다. 로케일은 en-US로 가정합니다. </p> + +<ol> + <li> + <p><code>"overview"</code> — 값은 배열이고, API 오버뷰 문서의 슬러그입니다. 하나인 경우 "Fetch API"이면 다음 같은 링크를 만듭니다. <a href="/en-US/docs/Web/API/Fetch_API">https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API</a>.</p> + </li> + <li> + <p><code>"interfaces"</code> — 해당 API의 인터페이스 전체 목록을 담은 배열 입니다. 값이 "Body"이면 다음 과 같은 링크를 만듭니다. <a href="/en-US/docs/Web/API/Body">https://developer.mozilla.org/en-US/docs/Web/API/Body</a>.</p> + </li> + <li> + <p><code>"methods"</code> — the value is an array that should contain any methods the spec adds to interfaces associated with other APIs, such as instantiation methods created on {{domxref("Navigator")}} or {{domxref("Window")}}. If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. "WindowOrWorkerGlobalScope.fetch()" results in a link being made to <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch</a>.</p> + </li> + <li> + <p><code>"properties"</code> — the value is an array that should contain all of the properties associated with the API. This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. "Headers.append" results in a link being made to <a href="/en-US/docs/Web/API/Headers/append">https://developer.mozilla.org/en-US/docs/Web/API/Headers/append</a>.</p> + </li> + <li> + <p><code>"events"</code> — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. "animationstart" results in a link being made to <a href="/en-US/docs/Web/Events/animationstart">https://developer.mozilla.org/en-US/docs/Web/Events/animationstart</a>.</p> + </li> + <li> + <p><code>"guides"</code> — the value is an array containing one or more objects that define links to guides explain how to use the API. Each object contains two submembers — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. As an example, the following object:</p> + + <pre class="brush: json notranslate">{ "url": "/docs/Web/API/Detecting_device_orientation", +"title": "Detecting device orientation" }</pre> + + <p>Creates a link with the title "Detecting device orientation", which points to <a href="/en-US/docs/Web/API/Detecting_device_orientation">https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation</a>.</p> + </li> +</ol> + +<h3 id="API_Submembers_and_Tags">API Submembers and Tags</h3> + +<p>Some submembers are automatically discovered from child pages, based on page tags. Pages under the top-level API are crawled each time the sidebar is rendered, and entries are automatically created for methods ("Method" tag), properties ("Property" tag), and constructors ("Constructor" tag).</p> + +<p>Submembers are automatically decorated with warning icons based on tags as well. Decorations are added for experimental ("Experimental" tag), non-standard ("Non Standard" or "Non-standard" tag), deprecated ("Deprecated" tag), or obsolete ("Obsolete" tag) submembers.</p> + +<p>Further information about tag-based processing is available <a href="https://github.com/mdn/kumascript/blob/master/macros/APIRef.ejs">in the APIRef source</a>.</p> + +<h3 id="Inserting_the_sidebar_in_your_pages">Inserting the sidebar in your pages</h3> + +<p>Once you've added an entry for your API into GroupData.json, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the \{{APIRef}} macro, which takes the name you used for your API in GroupData as a parameter. As an example, the <a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a>'s sidebar is included in its pages with the following:</p> + +<p>\{{APIRef("WebVR API")}}</p> diff --git a/files/ko/mdn/structures/api_references/index.html b/files/ko/mdn/structures/api_references/index.html new file mode 100644 index 0000000000..c521b5f4ec --- /dev/null +++ b/files/ko/mdn/structures/api_references/index.html @@ -0,0 +1,58 @@ +--- +title: API 레퍼런스 +slug: MDN/Structures/API_references +tags: + - API + - 가이드 + - 레퍼런스 + - 봉사 +translation_of: MDN/Structures/API_references +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">웹에서 사용 가능한 기술 중 클라이언트 측 자바스크립트 API가 차지하는 비중은 상당히 높습니다. 그렇기 때문에, MDN은 API의 기능과 사용법을 설명하는 광범위한 참조 자료를 보유하고 있습니다. 이 안내 문서는 이런 API 참고 자료를 MDN에 생성하는 방법을 설명합니다. </p> + +<h2 id="사전_준비">사전 준비</h2> + +<p>API를 문서화 하려면 다음이 가능해야 합니다. </p> + +<ol> + <li>최종 버전의 스팩: 그 API를 다루는 스팩의 단계가 W3C 최종 권고안인지, 초안인지는 관계없지만, 최종 버전의 스팩을 참조해야 합니다. 보통은 웹에서 쉽게 검색할 수 있으며, 그 스팩의 모든 버전의 문서에는 보통 최종 버전으로의 링크가 "lastest draft"등의 제목으로 걸려있습니다. </li> + <li>최신 모던 브라우저: 여러분이 문서화할 기능들은 정식 버전이 아닌 <a href="https://nightly.mozilla.org/">파이어폭스 나이틀리</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">크롬 카나리</a>와 같은 실험 버전에서 지원할 가능성이 높습니다. 앞서가는 실험적인 API를 문서화 한다면 더욱 이런 버전의 브라우저를 사용해야 합니다. </li> + <li>데모/블로그 글/다른 정보: 가능하면 최대한 정보를 찾아보세요. 그 API가 어떻게 동작하는지 스스로 익숙히는 좋은 출발점이 됩니다. 주 인터페이스, 프로퍼티, 메서드가 무엇인지, 주요한 유즈 케이스가 어떻게 되는지 배우고, 어떻게 그 기능을 간단시 서술할지 고민하세요. </li> + <li>기술문의 활용: API 표준화에 참여했거나 브라우저에서 그 스팩을 구현한 누군가에게 기술문의를 할 수 있는 나만의 연락처를 찾을 수 있다면 정말 좋습니다. 다음을 참고하세요. + <ul> + <li>관련 업무를 보는 회사에서 근무한다면 사내 주소록</li> + <li>그 API에 대한 토론 채널에 참여한 공개 메일링 리스트. 모질라의 <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a>, <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> 목록, <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a> 같은 W3C 목록 참고</li> + <li>스팩 문서. 예를 들면 <a href="https://webaudio.github.io/web-audio-api/">Web Audio API 문서</a> 상단에는 저자들의 연락처가 있음.</li> + </ul> + </li> +</ol> + +<h2 id="문서_구조">문서 구조</h2> + +<dl> + <dt><a href="/ko/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">API 레퍼런스 문서에 필요한 것은 무엇일까요? </a></dt> + <dd>이 문서는 완벽한 API 레퍼런스 문서에 필요한 것들을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Page_types">페이지 타입</a></dt> + <dd>MDN에서 반복적으로 사용되는 페이지 타입들이 있습니다. 이 문서는 그 타입들의 목적을 설명하고 신규 문서를 만들때 사용할 수 있는 템플릿 예제를 제공합니다. </dd> +</dl> + +<h2 id="페이지의_기능">페이지의 기능</h2> + +<p>API 레퍼런스 문서를 위한 페이지 기능을 생성하는 방법을 설명합니다. </p> + +<dl> + <dt><a href="/ko/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API 레퍼런스 사이드바</a></dt> + <dd>작성한 MDN API 레퍼런스 문서에 사이드바를 추가할 때, 여러분은 API와 관련된 인터페이스 튜토리얼, 다른 자료 링크를 맘대로 출력할 수 있습니다. 이 문서는 그 방법을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Syntax_sections">API 문법 섹션</a></dt> + <dd>MDN 참조 문서에서 문법 섹션은 그 기능이 가지고 있는 정확한 문법을 기술한 박스형태를 띄고 있다. (어떤 매개변수가 사용가능한지, 어떤 것이 옵션인지 등) 그 문서는 레퍼런스 문서를 위한 문법 섹션 작성법에 대해 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Code_examples">예제 코드</a></dt> + <dd>웹 플랫폼 기능 사용법을 설명하는 페이지에는 어김없이 많은 예제 코드가 있습니다. 이 문서는 페이지에 예제 코드를 추가하기 위한 각각의 가능한 메카니즘을 기술합니다. 무엇을 언제 사용해야 하는지도 함께요.</dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Specification_tables">스펙 테이블</a></dt> + <dd>MDN의 모든 레퍼런스 페이지는 API나 기술이 정의된 스팩, 또는 그 스팩에 대한 정보를 제공해야 합니다. 이 문서는 테이블의 형태와 제작 방법을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Compatibility_tables">호환성 테이블</a></dt> + <dd>MDN은 오픈 웹 문서, 즉 모든 브라우저에서 공유되는 DOM, HTML, CSS, JavaScript, SVG 등과 같은 기술 문서를 위한 호환성 테이블 표준을 가지고 있습니다. 이 문서는 호환성 데이터를 MDN 페이지에 추가하는 기능 사용법을 다룹니다. </dd> +</dl> diff --git a/files/ko/mdn/structures/compatibility_tables/index.html b/files/ko/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..2d1c19eda8 --- /dev/null +++ b/files/ko/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,496 @@ +--- +title: 호환성 표 +slug: MDN/Structures/Compatibility_tables +translation_of: MDN/Structures/Compatibility_tables +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">MDN에는 우리의 열린 웹 문서화(즉 모든 브라우저가 공유하는 DOM, HTML, CSS, JavaScript, SVG 등의 기술에 대한 문서화) 의 호환성 표를 위한 표준 형식이 있습니다. 이 글은 우리의 기능들을 이용하여 MDN 페이지들에 호환성 데이터를 추가하는 방법을 다룹니다.</p> + +<div class="warning"> +<p><strong>중요</strong>: <strong><em>데이터가 생성되는 방법이 바뀌었습니다</em></strong>. 예전에는 페이지에 넣는 표의 값을 수동으로 넣었습니다. 이 방법은 비효율적이고 유지보수를 어렵도록 하며 데이터가 유연하지 못하게 만듭니다. 그래서 브라우저 호환 데이터를 깃허브 레포지토리(주소: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>)로 옮기고 호환성 표를 코드를 통해 생성하는 방식으로 바꾸었습니다.</p> + +<p>In this guide, we document the new way to add compat data to MDN, but we've still kept documentation covering the old way, as you'll see manual tables on MDN for a while. If you need to see the old documentation, check out our <a href="/en-US/docs/MDN/Contribute/Structures/Old_compatibility_tables">Old compatibility tables</a> article.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: If you need any help with any steps of this guide, you are welcome to contact us at the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>.</p> +</div> + +<h2 id="How_to_access_the_data_repo">How to access the data repo</h2> + +<p>The data is stored in a GitHub repo — see <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>. To access it, you need to get a GitHub account, fork the browser-compat-data repo over to your own account, then clone your fork onto your local machine.</p> + +<h2 id="Choosing_a_feature_to_add_data_for">Choosing a feature to add data for</h2> + +<p>First of all, find a feature that you want to add browser-compat-data for. This could be an HTML element, CSS property, JS language feature or JS API interface, for example. We would like to encourage you to work on API features, as we already have people working on HTML, JS, and CSS. You can find the status of features that need their data adding to the repo on our <a href="https://docs.google.com/spreadsheets/d/1ivgyPBr9Lj3Wvj5kyndT1rgGbX-pGggrxuMtrgcOmjM/edit#gid=926663640">Browser Compat Data migration</a> spreadsheet.</p> + +<p>The process for using this is as follows:</p> + +<ol> + <li>Go ahead and choose a feature that is not already being worked on or complete. Put your name in the "Who" column, preferably along with your MDN username so we can find your email address and contact you if we need to.</li> + <li>If the feature you want to work on is not already listed in the spreadsheet, add rows for it in an appropriate place, copying the format that is already there. You should also use the same granularity (e.g. per element for HTML, per property or selector for CSS, per object for JS, per interface for APIs).</li> + <li>Once you've started work on adding the data, put the status to "In progress".</li> + <li>Once you've added the data and submitted a pull request to the main repo, put the status to "PR done".</li> + <li>As your data is merged to the repo, then added to the npm package, update the status as necessary.</li> + <li>Once you've updated the documentation page(s) for your feature to use the new macro to dynamically generate the appropriate data table on each page, set the status to "Article updated". At this point, you are done.</li> +</ol> + +<h2 id="Preparing_to_add_the_data">Preparing to add the data</h2> + +<p>Before adding some new data, you should make sure that your fork is up-to-date with the main repo (it contains the same content), create a new branch inside your fork to contain your additions, then pull that branch into your local clone so you can start working inside it:</p> + +<p>Let's look at a simple way to make sure your fork is to-to-date is as follows:</p> + +<h3 id="Adding_the_main_browser-compat-data_repo_as_a_remote">Adding the main browser-compat-data repo as a remote</h3> + +<p>Go to your local clone of your fork in your terminal/command line, and add a remote pointing to the main (upstream) repo like so (you only need to do this once):</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p>If you are unsure whether you've done this, you can check what remotes your repo has using</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="Updating_your_fork_with_the_remotes_content">Updating your fork with the remote's content</h3> + +<p>Now, whenever you want to update your fork, you can do so by:</p> + +<ol> + <li> + <p>Making sure you are in the master branch:</p> + + <pre class="brush: bash notranslate">git checkout master</pre> + </li> + <li> + <p>fetching the up-to-date repo contents using the following:</p> + + <pre class="brush: bash notranslate">git fetch upstream</pre> + </li> + <li> + <p>rebasing the contents of your master with the main repo's contents:</p> + + <pre class="brush: bash notranslate">git rebase upstream/master</pre> + </li> + <li> + <p>pushing these updates back to your remote fork using this:</p> + + <pre class="brush: bash notranslate">git push -f</pre> + </li> +</ol> + +<h3 id="Creating_a_new_branch_to_do_your_work_in">Creating a new branch to do your work in</h3> + +<p>Next, go to your remote fork (it will be at <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) and create a new branch to store your changes for this data addition. This can be done by:</p> + +<ol> + <li>Clicking on the "Branch: Master" button.</li> + <li>Entering a new branch name into the "Find or create a branch..." text field.</li> + <li>Pressing the resulting "Create branch <em>name-of-branch</em> from Master" button.</li> +</ol> + +<p>For example, if you were wanting to add data for the WebVR API, you'd create a branch called something like "webvr".</p> + +<h3 id="Switching_to_the_new_branch">Switching to the new branch</h3> + +<p>At this point, go back to your terminal/command line, and update your fork's local clone to include your new branch using the following command:</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>Now switch to your new branch using this:</p> + +<pre class="brush: bash notranslate">git checkout<em> name-of-branch</em></pre> + +<p>You should now be ready to start adding your data!</p> + +<h2 id="Adding_the_data">Adding the data</h2> + +<p>To add the data, you need to create a new file or files to store your compat data in. The files you need to create differ, depending on what technology you are working on:</p> + +<ul> + <li>HTML: One file per HTML element, contained in <a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a>. The file should be called the name of the element, all in lower case, e.g. <code>div.json</code>.</li> + <li>CSS: One file per CSS property or selector, contained in the appropriate directory (see <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a>). The file should be called the name of the feature, all in lower case, e.g. <code>background-color.json</code>, or <code>hover.json</code>.</li> + <li>JS: One file per JS object, contained in <a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a>. The file should be called the exact name of the object, with the casing preserved, e.g. <code>Date.json</code> or <code>InternalError.json</code>.</li> + <li>APIs: One file per interface contained in the API, put in <a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a>. Each file should be called the exact name of the interface, with the casing preserved, e.g. The WebVR API has <code>VRDisplay.json</code>, <code>VRDisplayCapabilities.json</code>, etc.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: You'll notice that the repo also contains data for <a href="/en-US/Add-ons/WebExtensions">Browser Extensions</a> and <a href="/en-US/docs/Web/HTTP">HTTP</a>. These data sets are basically finished as they stand, but more features may need to be added in the future.</p> +</div> + +<p>Each file you create has to follow the pattern defined in the schema contained within our repo; you can see the <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md">detailed schema description here</a>.</p> + +<h3 id="Basic_compat_data_structure">Basic compat data structure</h3> + +<p>Let's look at an example. CSS property JSON files for example need the following basic structure:</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>You have the <code>css</code> object, inside of which is a <code>properties</code> object. Inside the <code>properties</code> object, you need one member for each of the specific features you want to define the compat data for. Each of these members has a <code>__compat</code> member, inside of which the actual data goes.</p> + +<p>The above data is found in the <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a> file — compare this to the <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">rendered border-width support table on MDN</a>.</p> + +<p>Other types of features work in the same way, but with different object names:</p> + +<ul> + <li>CSS selectors work in basically the same way as CSS properties, except that the top-level object structure is <code>css.selectors</code> instead of <code>css.properties</code>. See <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> for an example.</li> + <li>HTML data works in basically the same way, except that the top-level object structure is <code>html.elements</code>. See <code>article.json</code> for an example.</li> + <li>The top level object structure for JS built-in objects is <code>javascript.builtins</code>; see <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> for an example.</li> +</ul> + +<div> +<p>In HTML, CSS, and JS pages, you'll normally only need one feature. API interfaces work slightly differently — they always have multiple sub-features (see {{anch("Sub-features")}}, below).</p> + +<h3 id="Basic_structure_inside_a_feature">Basic structure inside a feature</h3> + +<p>Inside a feature <code>__compat</code> member, you need to include the following members:</p> + +<ul> + <li><code>mdn_url</code>: Contains the URL of the reference page for this feature on MDN. Note that this needs to be written without the locale directory inside, e.g. <code>/docs/...</code> not <code>/docs/en-US/...</code> (or whatever). This is added in by the macro when the data is put on the page, for localization purposes.</li> + <li><code>support</code>: Contains members representing the browser support information for this feature in all the different browsers we want to report.</li> + <li><code>status</code>: Contains members reporting the standards track status of this feature.</li> +</ul> + +<p>The names of the browser members are defined in the schema (see <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">Browser identifiers</a>). You should use the full list of currently defined identifiers. If you wish to add another browser, talk to us first, as this could have a wide-ranging impact and should not be done without careful thought.</p> + +<p>In a basic browser compat data file, you'll only need to include "version_added" inside the browser identifier members (we'll cover {{anch("Advanced cases")}} later on). The different values you might want to include are as follows:</p> + +<ul> + <li>A version number: If you know the exact version in which a browser started to support your feature, use a string representing the number, e.g. "47".</li> + <li><code>true</code>: If a browser supports a feature but you don't know the exact version number, use the value <code>true</code>. This equivalent to the <code>\{{CompatVersionUnknown}}</code> macro call in the old manual tables.</li> + <li><code>false</code>: If a browser does not support a feature, use the value <code>false</code>. This is equivalent to the the <code>\{{CompatNo}}</code> macro call in the old manual tables.</li> + <li><code>null</code>: If you don't know whether a browser supports a feature or not, use the value <code>null</code>. This is equivalent to the <code>\{{CompatUnknown}}</code> macro call in the old manual tables.</li> +</ul> + +<p>Inside the <code>status</code> member, you'll include three submembers:</p> + +<ul> + <li> "experimental": This should be set to <code>true</code> if the feature is <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>, or <code>false</code> otherwise.</li> + <li>"standard_track": This should be set to <code>true</code> if a feature is on some kind of standards track (most commonly W3C/WHATWG, but there are also other standards efforts such as Khronos, TC39, etc.) or <code>false</code> otherwise.</li> + <li>"deprecated": This should be set to <code>true</code> if the feature is <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>, or <code>false</code> otherwise.</li> +</ul> + +<p>The feature data for <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">border-width</a> (also see <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a>) is shown below as an example:</p> + +<pre class="brush: json notranslate">"__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width", + "support": { + "chrome": { + "version_added": "1" + }, + "webview_android": { + "version_added": "2" + }, + "edge": { + "version_added": true + }, + "edge_mobile": { + "version_added": true + }, + "firefox": { + "version_added": "1" + }, + "firefox_android": { + "version_added": "1" + }, + "ie": { + "version_added": "4" + }, + "ie_mobile": { + "version_added": "6" + }, + "opera": { + "version_added": "3.5" + }, + "opera_android": { + "version_added": "11" + }, + "safari": { + "version_added": "1" + }, + "safari_ios": { + "version_added": "3" + } + }, + "status": { + "experimental": false, + "standard_track": true, + "deprecated": false + } +}</pre> + +<h4 id="Adding_a_description">Adding a description</h4> + +<p>There is a fourth, optional, member that can go inside the __compat member — <code>description</code>. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so:</p> + +<pre class="brush: json notranslate">{ + "api": { + "AbortController": { + "__compat": { + ... + }, + "AbortController": { + "__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController", + "description": "<code>AbortController()</code> constructor", + "support": { + ... + } + } + } + + ... etc. + } + } +}</pre> + +<h3 id="Sub-features">Sub-features</h3> + +<p>In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was addded much later in the specification's life and is only supported in a couple of browsers.</p> + +<p>As an example, see the <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/background-color.json">compat data</a> and <a href="/en-US/docs/Web/CSS/background-color">corresponding MDN page</a> for the <code>background-color</code> property. The basic support exists inside the <code>__compat</code> object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own <code>__compat</code> object.</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "background-color": { + "__compat": { + ... + }, + "alpha_ch_for_hex": { + "__compat": { + ... + }, + } + } + } + } +}</pre> + +<p>For an API, you've got the top two levels defined as <code>api.<em>name-of-the-interface</em></code>, then a top-level <code>__compat</code> section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this:</p> + +<pre class="brush: json notranslate">{ + "api": { + "VRDisplay": { + "__compat": { + ... + }, + "cancelAnimationFrame": { + "__compat": { + ... + } + }, + "capabilities": { + "__compat": { + ... + } + }, + + ... etc. + + } + } +}</pre> + +<p>See <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a> for a full example.</p> +</div> + +<h2 id="Adding_data_Advanced_cases">Adding data: Advanced cases</h2> + +<p>There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data.</p> + +<h3 id="Including_a_footnote">Including a footnote</h3> + +<p>Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for {{domxref("VRDisplay.capabilities")}} (see also <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a>) (at the time of writing) had a footnote "<span class="pl-s">Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this:</span></p> + +<pre class="brush: json notranslate">"chrome_android": { + "version_added": true, + "notes": "Currently supported only by Google Daydream." +}</pre> + +<h3 id="Including_a_vendor_prefix">Including a vendor prefix</h3> + +<p>If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. imagine you had a feature that was supported with a <code>-moz-</code> prefix in Firefox. To specify this in the compat data, you'd need to add a "prefix" submember inside the relevant "firefox" submember. It would look something like this:</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": true, + "prefix": "-moz-" +}</pre> + +<h3 id="Including_browser_preferences_or_flags">Including browser preferences or flags</h3> + +<p>Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag.</p> + +<p>To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members:</p> + +<ul> + <li>"type": The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using <code>about:config</code> in Firefox, or <code>chrome://flags</code> in Chrome), but you might also sometimes use a value of <span class="pl-s"><span class="pl-pds">"</span>compile_flag<span class="pl-pds">", which is a preference set when the browser build is compiled.</span></span></li> + <li>"name": This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in <code>chrome://flags</code>.</li> + <li>"value_to_set": This is a string representing the value that needs to be set on the preference, for example "true".</li> +</ul> + +<p>So to add a preference/flag to the Chrome support for a feature, you'd do something like this:</p> + +<pre class="brush: json notranslate">"chrome": { + "version_added": "50", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] +},</pre> + +<p>If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "57", + "flags": [ + { + "type": "preference", + "name": "dom.streams.enabled", + "value_to_set": "true" + }, + { + "type": "preference", + "name": "javascript.options.streams", + "value_to_set": "true" + } + ] +},</pre> + +<h3 id="Including_a_version_where_support_was_removed">Including a version where support was removed</h3> + +<p>Sometimes a feature will be added in a certain browser version, but then removed again as the feature is deprecated. This can be easily represented using the "version_removed" submember, which takes as its value a string representing the version number it was removed on. For example:</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "35", + "version_removed": "47", +},</pre> + +<h3 id="Including_multiple_support_points_for_the_same_browser_entry">Including multiple support points for the same browser entry</h3> + +<p>Sometimes you'll want to add multiple support data points for the same browser inside the same feature.</p> + +<p>As an example, the {{cssxref("text-align-last")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/text-align-last.json">text-align-last.json</a>) was added to Chrome in version 35, supported behind a pref.</p> + +<p>The support mentioned above was then removed in version 47; also in version 47, support was added for <code>text-align-last</code> enabled by default.</p> + +<p>To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object:</p> + +<pre class="brush: json notranslate">"chrome": [ + { + "version_added": "47" + }, + { + "version_added": "35", + "version_removed": "47", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] + } +],</pre> + +<div class="note"> +<p><strong>Note</strong>: You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info.</p> +</div> + +<h3 id="Including_an_alternative_name">Including an alternative name</h3> + +<p>Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized.</p> + +<p>To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member.</p> + +<div class="note"> +<p><strong>Note</strong>: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.</p> +</div> + +<p>Let's look at an example. The {{cssxref("border-top-right-radius")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/2a0cc3f6bb17aa4345441bed47a059dffd847793/css/properties/border-top-right-radius.json">border-top-right-radius.json</a>) was supported in Firefox:</p> + +<ul> + <li>From version 4 onwards with the standard name <code>border-top-right-radius</code>.</li> + <li>From version 49 onwards with a <code>-webkit-</code> prefix, for browser compatibility purposes.</li> + <li>From version 1 onwards with the alternative name <code>-moz-border-radius-topright</code>. Support for this alias was removed in version 12.</li> +</ul> + +<p>To represent this in the data, we used the following JSON:</p> + +<pre class="brush: json notranslate">"firefox": [ + { + "version_added": "4", + "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0." + }, + { + "prefix": "-webkit-", + "version_added": "49", + "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>." + }, + { + "alternative_name": "-moz-border-radius-topright", + "version_added": "1", + "version_removed": "12" + } +],</pre> + +<h2 id="Pushing_a_change_back_to_the_main_repo">Pushing a change back to the main repo</h2> + +<p>Once you are finished with adding your compat data, you should first test it using the following commands:</p> + +<ul> + <li><code>npm run lint</code> — tests all the compat data to make sure the JSON is valid, and is written in the correct style, for example correct indentation, no missing commas, etc. It will print out a long list of file names and test results; if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc.</li> + <li><code>npm run show-errors</code> — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used.</li> + <li><code>npm run render dotted.path.to.feature</code> — allows you to preview the markup for the compat table for a data file in the repo. As an example, <code>npm run render css.properties.background</code> shows the table markup for the {{cssxref("background")}} property.</li> +</ul> + +<p>If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this:</p> + +<pre class="brush: bash notranslate">git add . +git commit -m 'adding compat data for name-of-feature' +git push</pre> + +<p>Now go to your remote fork (i.e. <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen.</p> + +<p>At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted.</p> + +<h2 id="Inserting_the_data_into_MDN_pages">Inserting the data into MDN pages</h2> + +<p>Once your new data has been included in the main repo, you can start dynamically generating browser compat tables based on that data on MDN pages using the \{{Compat}} macro. This takes a single parameter, the dot notation required to walk down the JSON data and find the object representing the feature you want to generate the compat table for.</p> + +<p>Above the macro call, to help other contributors finding their way, you should add a hidden text that is only visible in MDN contributors in edit mode:</p> + +<pre class="brush: html notranslate"><div class="hidden"> +<p>The compatibility table on this page is generated from structured data. +If you'd like to contribute to the data, please check out +<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> +and send us a pull request.</p> +</div></pre> + +<p>As an example, on the {{httpheader("Accept-Charset")}} HTTP header page, the macro call looks like this: \{{Compat("http.headers.Accept-Charset")}}. If you look at the <a href="https://github.com/mdn/browser-compat-data/blob/master/http/headers/accept-charset.json">accept-charset.json</a> file in the repo, you'll see how this is reflected in the JSON data.</p> + +<p>As another example, The compat table for the {{domxref("VRDisplay.capabilities")}} property is generated using \{{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):</p> + +<hr> +<div class="hidden"> +<p>The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> +</div> + +<p>{{Compat("api.VRDisplay.capabilities")}}</p> + +<div class="note"> +<p><strong>Note</strong>: The filenames often match the labels given to the interfaces inside the JSON structures, but it is not always the case. When the macro calls generate the tables, they walk through all the files until they find the relevant JSON to use, so the filenames are not critical. Saying that, you should always name them as intuitively as possible.</p> +</div> diff --git a/files/ko/mdn/structures/index.html b/files/ko/mdn/structures/index.html new file mode 100644 index 0000000000..7934f5f1f6 --- /dev/null +++ b/files/ko/mdn/structures/index.html @@ -0,0 +1,18 @@ +--- +title: 문서 구조 +slug: MDN/Structures +tags: + - MDN 메타 + - 문서구조 + - 시작하기 +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<div>MDN에는 정보를 일관되게 표현하기 위해서 반복해서 사용하는 문서 구조들이 있습니다. 여기선 여러분이 글을 작성하고 수정, 번역할 때 받아들이고 적용할 뿐만 아니라 개선할 수 있도록 그 구조에 대해 설명합니다.</div> + +<div> </div> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ko/mdn/structures/macros/commonly-used_macros/index.html b/files/ko/mdn/structures/macros/commonly-used_macros/index.html new file mode 100644 index 0000000000..8038d19eba --- /dev/null +++ b/files/ko/mdn/structures/macros/commonly-used_macros/index.html @@ -0,0 +1,220 @@ +--- +title: 흔히 쓰는 매크로 +slug: MDN/Structures/Macros/Commonly-used_macros +tags: + - Reference +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">이 페이지는 MDN에서 사용하기 위해 만든 많은 범용 매크로를 나열합니다. 이 매크로 사용법에 관한 정보는, <a href="/ko/docs/MDN/Contribute/Content/Macros">매크로 사용하기</a> 및 <a href="/ko/docs/MDN/Contribute/Editor/Links#Using_link_macros">링크 매크로 사용하기</a>를 참조하세요.</span> 드물게, 특별한 문맥에서만 쓰이거나 사라질(deprecated) 매크로에 관한 정보는 <a href="/ko/docs/MDN/Contribute/Structures/Macros/Other">기타 매크로</a>를 참조하세요. <a href="/ko/docs/templates" title="complete list of all macros on MDN">MDN의 모든 매크로 전체 목록</a>도 있습니다.</p> + +<p>사용 가능 스타일에 관한 <a href="/ko/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 스타일 안내서</a>도 참조하세요.</p> + +<h2 id="링크하기">링크하기</h2> + +<h3 id="단일_하이퍼링크_생성">단일 하이퍼링크 생성</h3> + +<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">대개, 임의(arbitrary) 링크 생성을 위해 매크로를 사용할 필요가 없습니다. 링크를 만들기 위해 에디터 인터페이스의 <strong>링크</strong> 버튼을 사용하세요</p> + +<ul> + <li>{{TemplateLink("Glossary")}} 매크로는 MDN <a href="/ko/docs/Glossary" title="glossary">용어사전</a> 내 지정된 용어(term) 항목에 대한 링크를 만듭니다. 이 매크로는 하나는 필수며 둘은 선택인 매개변수를 취합니다: + + <ol> + <li>용어명 (가령 "HTML").</li> + <li>용어명 대신 글에 표시할 텍스트 (이건 드물게 쓰임). {{optional_inline}}</li> + <li>이 매개변수가 지정되고 0이 아닌 경우, 보통 용어사전 링크에 적용된 사용자 정의 스타일링은 적용되지 않습니다. {{optional_inline}}</li> + </ol> + + <p>예:</p> + + <ul> + <li>\{{Glossary("HTML")}}은 {{Glossary("HTML")}}이 됩니다</li> + <li>\{{Glossary("CSS", "Cascading Style Sheets")}}는 {{Glossary("CSS", "Cascading Style Sheets")}}가 됩니다</li> + <li>\{{Glossary("HTML", "", 1)}}은 {{Glossary("HTML", "", 1)}}이 됩니다</li> + </ul> + </li> +</ul> + +<h3 id="참고서_내_페이지에_링크하기">참고서 내 페이지에 링크하기</h3> + +<p>MDN의 특정 참고서(reference) 영역 내 페이지에 링크하는 다양한 매크로가 있습니다.</p> + +<ul> + <li>{{TemplateLink("cssxref")}}는 <a href="/ko/docs/Web/CSS/CSS_Reference" title="CSS Reference">CSS 참고서</a> 내 페이지에 링크합니다.<br> + 예: <code>\{{cssxref("cursor")}}</code>, 결과: {{ cssxref("cursor") }}.</li> + <li>{{TemplateLink("domxref")}}는 DOM 참고서 내 페이지에 링크합니다; 끝에 괄호를 포함하는 경우, 템플릿은 함수 이름처럼 보이도록 표시해야 함을 압니다. 예를 들어, <span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span>은 {{ domxref("document.getElementsByName()") }}이 되고 <code>\{\{domxref("Node")\}\}</code>는 {{ domxref("Node") }}가 됩니다.</li> + <li>{{TemplateLink("event")}}는 DOM Event 참고서 내 페이지에 링크합니다, 예: \{{event("change")}}는 {{event("change")}}가 됩니다.</li> + <li>{{TemplateLink("HTMLElement")}}는 HTML 참고서 내 HTML 요소(element)에 링크합니다.</li> + <li>{{TemplateLink("htmlattrxref")}}는 HTML attribute, 전역 attribute 설명 (attribute명만 지정한 경우) 또는 (attribute명 및 요소명을 지정한 경우) 지정 요소와 관련된 attribute에 링크합니다. 예를 들어, <code>\{\{htmlattrxref("lang")\}\}</code>은 이 링크를 만듭니다: {{htmlattrxref("lang")}}.<code> </code> <code>\{\{htmlattrxref("type","input")\}\}</code>은 이 링크를 만듭니다: {{htmlattrxref("type","input")}}.</li> + <li>{{TemplateLink("jsxref")}}는 <a href="/ko/docs/Web/JavaScript/Reference" title="JavaScript Reference">JavaScript 참고서</a> 내 페이지에 링크합니다.</li> + <li>{{TemplateLink("SVGAttr")}}은 특정 SVG attribute에 링크합니다. 예를 들어, <code>\{\{SVGAttr("d")\}\}</code>은 이 링크를 생성합니다: {{SVGAttr("d")}}.</li> + <li>{{TemplateLink("SVGElement")}}는 SVG 참고서 내 SVG 요소에 링크합니다.</li> +</ul> + +<h3 id="버그_및_IRC에_링크하기">버그 및 IRC에 링크하기</h3> + +<ul> + <li>버그 + <ul> + <li>{{TemplateLink("bug")}}는 다음 구문을 사용하여 쉽게 bugzilla.mozilla.org의 버그에 링크할 수 있습니다: <code>\{\{Bug(123456)\}\}</code> 이 구문의 결과는: {{ Bug(123456) }}.</li> + <li>{{TemplateLink("WebkitBug")}}는 WebKit 버그 데이터베이스 내 버그로 링크를 삽입합니다. 예를 들어, <code>\{\{WebkitBug(31277)\}\}</code>은 {{ WebkitBug(31277) }}를 삽입합니다.</li> + </ul> + </li> + <li>{{TemplateLink("IRCLink")}}는 지정된 IRC 채널로의 링크를 삽입합니다, 하는 일과 IRC 클라이언트가 필요함을 말하는 툴팁을 갖춘.</li> +</ul> + +<h3 id="여러_페이지_안내서를_위한_내비게이션_보조">여러 페이지 안내서를 위한 내비게이션 보조</h3> + +<p>{{TemplateLink("Previous")}}, {{TemplateLink("Next")}} 및 {{TemplateLink("PreviousNext")}}는 연속글의 일부인 글을 위한 내비게이션 컨트롤을 제공합니다. 단방향 템플릿의 경우, 필요한 유일한 매개변수는 연속글의 이전 또는 다음 글의 위키 주소입니다. {{TemplateLink("PreviousNext")}}의 경우, 필요한 두 매개변수는 해당 글의 위키 주소입니다. 첫 번째 매개변수는 이전 글이고 두 번째는 다음 글입니다.</p> + +<h2 id="코드_샘플">코드 샘플</h2> + +<h3 id="실시간_샘플">실시간 샘플</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}}은 페이지 상에 코드 샘플의 출력을 포함할 수 있습니다, <a href="/ko/docs/MDN/Contribute/Structures/Live_samples" title="Live samples">실시간 샘플</a>에 설명된 대로.</li> + <li>{{TemplateLink("LiveSampleLink")}}는 페이지 상에 코드 샘플의 출력을 포함하는 페이지로의 링크를 만듭니다, <a href="/ko/docs/MDN/Contribute/Structures/Live_samples" title="Live samples">실시간 샘플</a>에 설명된 대로.</li> +</ul> + +<h3 id="첨부된_샘플_파일">첨부된 샘플 파일</h3> + +<ul> + <li>{{TemplateLink("Embed_text")}} 템플릿은 글 본문 내에 첨부된 텍스트 파일을 삽입할 수 있습니다. 이는 다운로드 가능하지만 글의 콘텐츠에 표시되기도 하는 코드 조각을 갖고 싶은 경우 유용합니다. 구문 강조를 위한 언어를 선택 사항으로 지정할 수도 있습니다; 지정하지 않은 경우, 텍스트는 강조 없이 삽입됩니다. 첫 번째 매개변수는 삽입할 첨부 파일명입니다; 두 번째는, 제공되는 경우 구문 강조기를 적용할 언어입니다, 가령 "javascript", "svg" 또는 "cpp".</li> + <li>{{TemplateLink("EmbedSVG")}}는 SVG 이미지로서 첨부된 XML 파일을 삽입합니다, 페이지 위에다. 첨부된 SVG 파일의 파일명을 지정하세요. 소스 그리고 같은 파일의 렌더링된 출력을 표시하기 위해 {{TemplateLink("Embed_text")}}와 동시에 이를 사용할 수 있습니다.</li> +</ul> + +<h2 id="사이드바_생성">사이드바 생성</h2> + +<p>거의 모든 대규모 페이지 컬렉션 용 템플릿이 있습니다. 보통은 참고서/안내서(guide)/지도서(tutorial)의 메인 페이지로 다시 링크하고 (이동 경로 표시(breadcrumb)가 때때로 이를 수행할 수 없기에 종종 필요함) 글을 적절한 항목(category)에 둡니다.</p> + +<ul> + <li>{{TemplateLink("CSSRef")}}는 CSS 참고서 페이지 용 사이드바를 생성합니다.</li> + <li>{{TemplateLink("HTMLRef")}}는 HTML 참고서 페이지 용 사이드바를 생성합니다.</li> + <li>{{TemplateLink("APIRef")}}는 Web API 참고서 페이지 용 사이드바를 생성합니다.</li> +</ul> + +<h2 id="범용_형식">범용 형식</h2> + +<h3 id="API_문서용_인라인_지시자indicator">API 문서용 인라인 지시자(indicator)</h3> + +<p>{{TemplateLink("optional_inline")}} 및 {{TemplateLink("ReadOnlyInline")}}은 API 문서에서 보통 객체의 속성 목록 또는 함수의 매개변수를 기술할 때 사용됩니다.</p> + +<p>용법: <code>\{{optional_inline()}}</code> 또는 <code>\{{ReadOnlyInline()}}</code>. 예:</p> + +<dl> + <dt><code>isCustomObject</code> {{ReadOnlyInline()}}</dt> + <dd>(<code>true</code>)면, 사용자 정의 객체임을 나타냅니다.</dd> + <dt>parameterX {{ optional_inline() }}</dt> + <dd>어쩌고 저쩌고...</dd> +</dl> + +<h2 id="상태_및_호환성_지시자">상태 및 호환성 지시자</h2> + +<h3 id="추가_매개변수가_없는_인라인_지시자">추가 매개변수가 없는 인라인 지시자</h3> + +<h4 id="비표준">비표준</h4> + +<p>{{TemplateLink("non-standard_inline")}}은 API가 표준화되지 않았고 표준 트랙에 없음을 나타내는 인라인 표시를 삽입합니다.</p> + +<h5 id="구문"><strong>구문</strong></h5> + +<p><code>\{{non-standard_inline}}</code></p> + +<h5 id="예">예</h5> + +<ul> + <li>아이콘: {{non-standard_inline}}</li> +</ul> + +<h4 id="실험용">실험용</h4> + +<p>{{TemplateLink("experimental_inline")}}은 API가 널리 구현되지 않고 앞으로 변경될 수 있음을 나타내는 인라인 표시를 삽입합니다.</p> + +<h5 id="구문_2">구문</h5> + +<p><code>\{{experimental_inline}}</code></p> + +<h5 id="예_2"><code>예</code></h5> + +<ul> + <li>아이콘: {{experimental_inline}}</li> +</ul> + +<h3 id="기술_지정을_지원하는_인라인_지시자">기술 지정을 지원하는 인라인 지시자</h3> + +<p>이 매크로에서 매개변수(지정된 경우)는 버전 번호가 뒤따르는 문자열 "html", "js", "css" 또는 "gecko" 중 하나여야 합니다.</p> + +<h4 id="Deprecated">Deprecated</h4> + +<p>{{TemplateLink("deprecated_inline")}}은 공식으로 사라질 API의 사용을 삼가도록 인라인 사라질(deprecated) 표시를 삽입합니다. <strong>주의:</strong> "사라질"은 더 이상 사용되지 않지만 여전히 기능함을 뜻합니다. 전혀 작동하지 않음을 뜻하는 경우, 용어 "안 씀(obsolete)"을 쓰세요.</p> + +<p>모든 브라우저에 쓰일 수 있는 영역(HTML, API, JS, CSS, …)에는 매개변수를 사용하지 마세요.</p> + +<h5 id="구문_3">구문</h5> + +<p><code>\{{deprecated_inline}}</code> 또는 <code>\{{deprecated_inline("gecko5")}}</code></p> + +<h5 id="예_3">예</h5> + +<ul> + <li>아이콘: {{deprecated_inline}}</li> + <li>배지: {{deprecated_inline("gecko5")}}</li> +</ul> + +<h4 id="Obsolete">Obsolete</h4> + +<p>{{TemplateLink("obsolete_inline")}}은 공식으로 안 쓰는(obsolete) 예를 들어 함수, 메서드 또는 속성이 사용을 막기 위해 인라인 안 씀 표시를 삽입합니다.</p> + +<p>모든 브라우저에 쓰일 수 있는 영역(HTML, API, JS, CSS, …)에는 매개변수를 사용하지 마세요.</p> + +<h5 id="구문_4">구문</h5> + +<p><code>\{{obsolete_inline}}</code> 또는 <code>\{{obsolete_inline("js1.8.5")}}</code></p> + +<h5 id="예_4">예</h5> + +<ul> + <li>아이콘: {{obsolete_inline}}</li> + <li>배지: {{obsolete_inline("js1.8.5")}}</li> +</ul> + +<h3 id="템플릿_배지">템플릿 배지</h3> + +<p>이 매크로는 대부분 <a href="/ko/docs/WebAPI">WebAPI</a> 페이지에 사용됩니다. 새 배지 생성 정보는 {{anch("Creating new badges")}} 참조.</p> + +<h3 id="페이지_또는_절_표제_지시자">페이지 또는 절 표제 지시자</h3> + +<p>이 템플릿들은 위에 설명한 자신의 인라인 짝(counterpart)과 같은 의미(semantics)를 갖습니다. 템플릿은 참고 페이지 내 메인 페이지 제목 (또는 가능한 경우 이동 경로 표시(breadcrumb) 내비게이션) 바로 아래에 놓여야 합니다. 페이지 상 절(section)에 표시하는데 사용될 수도 있습니다.</p> + +<ul> + <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li> + <li>{{TemplateLink("SeeCompatTable")}}은 "브라우저 호환성" 절을 제공하는 페이지에 사용되어야 합니다. 예: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li> + <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li> + <li>매개변수 있는 {{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} 모든 브라우저에 쓰일 수 있는 영역(HTML, APIs, JS, CSS, …)에는 매개변수를 사용하지 마세요.</li> + <li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li> + <li>매개변수 있는 {{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} 모든 브라우저에 쓰일 수 있는 영역(HTML, APIs, JS, CSS, …)에는 매개변수를 사용하지 마세요.</li> +</ul> + +<h3 id="기능을_웹_워커에서_이용가능한_지_나타내기">기능을 웹 워커에서 이용가능한 지 나타내기</h3> + +<p>{{TemplateLink("AvailableInWorkers")}} 매크로 기능이 <a href="/ko/docs/Web/API/Web_Workers_API">웹 워커</a> 컨텍스트에서 이용 가능한지를 나타내는 지역화된 메모 상자를 삽입합니다.</p> + +<h2 id="버전_정보_매크로">버전 정보 매크로</h2> + +<p>이 매크로는 콘텐츠가 특정 버전의 제품에만 해당됨을 나타내기 위해 사용됩니다.</p> + +<ul> + <li>{{TemplateLink("gecko_minversion_inline")}}: 가령: {{ gecko_minversion_inline("9.9") }}</li> + <li>{{TemplateLink("fx_minversion_inline")}}: 가령: {{ fx_minversion_inline("9.9") }}</li> +</ul> + +<ol> +</ol> + +<p> </p> + +<ol> +</ol> + +<p> </p> diff --git a/files/ko/mdn/structures/macros/index.html b/files/ko/mdn/structures/macros/index.html new file mode 100644 index 0000000000..3e27b26b8a --- /dev/null +++ b/files/ko/mdn/structures/macros/index.html @@ -0,0 +1,46 @@ +--- +title: 매크로 +slug: MDN/Structures/Macros +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - Structures +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN이 돌아가는 <a href="/ko/docs/MDN/Kuma" title="/ko/docs/MDN/Kuma">Kuma</a> 플랫폼은 매우 다양한 것들을 자동으로 수행할 수 있게 하는 강력한 매크로 시스템인, <a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript</a>를 제공합니다. 이 글은 글 내에서 MDN의 매크로를 호출하는 법에 관한 정보를 제공합니다.</span></p> + +<p><a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript 안내서</a>는 상세히 고찰한 MDN 상의 매크로 사용법을 제공합니다. 따라서 이 절은 더 짧은 개요입니다.</p> + +<h2 id="매크로가_구현되는_법">매크로가 구현되는 법</h2> + +<p>MDN의 매크로는 서버에서 실행되는 <a href="/ko/docs/Web/JavaScript">JavaScript</a> 코드로 구현되고, <a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>를 사용하여 해석됩니다. 그 위에 우리가 구현한 위키 중심 서비스 및 매크로를 위키 플랫폼 및 그 콘텐츠와 상호 작용하게 하는 기능을 제공하는 많은 라이브러리가 있습니다. 더 배우고 싶다면, <a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript 안내서</a>를 참조하세요.</p> + +<h2 id="콘텐츠에_매크로_사용하기">콘텐츠에 매크로 사용하기</h2> + +<p>실제로 매크로를 사용하려면, 괄호로 싸인 매개변수(가 있다면)와 함께 매크로 호출을 그저 중괄호 두 쌍으로 두르세요. 즉 다음과 같이:</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>매크로 호출에 관한 몇 가지 주의사항:</p> + +<ul> + <li>매크로 명은 대소문자를 구분하지만 일부는 흔한 대문자화(capitalization) 오류를 고치기 위해 만든 시도입니다. 따라서 매크로 명은 이름 내에 대문자를 사용할지라도 모두 소문자로 쓸 수 있고 보통 소문자로 시작하는 매크로 명을 대문자로 시작할 수 있습니다.</li> + <li>매개변수는 쉼표로 구분됩니다.</li> + <li>매개변수가 없다면, 괄호를 전부 뺄 수 있습니다. 즉 <code>\{{macroname()}}</code> 및 <code>\{{macroname}}</code>은 동일합니다.</li> + <li>숫자 매개변수는 따옴표로 묶거나 묶지 않을 수 있습니다. 알아서 하세요(그러나, 그 안에 여러 소수가 있는 버전 번호라면 따옴표로 묶어야 합니다).</li> + <li>오류가 생기면, 코드를 신중히 검토하세요. 무슨 일인지 여전히 파악할 수 없다면, 도움을 받기 위해 <a href="/ko/docs/MDN/Kuma/Troubleshooting_KumaScript_errors" title="Troubleshooting KumaScript errors">KumaScript 오류 해결</a>을 참조하세요.</li> +</ul> + +<p>매크로는 다량(heavily) 캐쉬됩니다; 어떠한 일련의 입력 값(매개변수 및 매크로가 실행되었을 URL과 같은 환경 값 모두)에 대해, 그 결과는 저장되고 재사용됩니다. 이는 매크로가 사실 매크로 입력이 바뀔 때만 실행됨을 뜻합니다.</p> + +<div class="note"> +<p><strong>주의:</strong> 페이지의 모든 매크로를 브라우저에서 페이지 강제 새로 고침(즉, shift-새로 고침)하여 재평가되게 강제할 수 있습니다.</p> +</div> + +<p>매크로는 더 큰 텍스트 블록 단순 삽입 또는 MDN의 다른 부분에서 콘텐츠를 교환하는 것처럼 간단하거나, 사이트의 일부를 검색하여 콘텐츠의 전체 색인 구축, 출력 스타일링 및 링크 추가처럼 복잡할 수 있습니다.</p> + +<p><a href="/ko/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="Commonly-used macros">흔히 쓰는 매크로</a> 페이지에서 가장 흔히 쓰는 매크로에 관하여 읽을 수 있습니다; 또한, 여기에 <a href="https://developer.mozilla.org/ko/docs/templates">모든 매크로 전체 목록</a>도 있습니다. 매크로 대부분은 상단에 주석으로 내장된 문서가 있습니다.</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ko/mdn/tools/index.html b/files/ko/mdn/tools/index.html new file mode 100644 index 0000000000..a890d6f76c --- /dev/null +++ b/files/ko/mdn/tools/index.html @@ -0,0 +1,16 @@ +--- +title: MDN 도구들 +slug: MDN/Tools +tags: + - MDN 메타 + - TopicStub + - 시작하기 +translation_of: MDN/Tools +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p>MDN은 진행 상황을 추적하고 콘텐츠를 관리하며 사이트의 최신 변경 사항을 따라하기 쉽게 해주는 많은 기능을 제공합니다.</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ko/mdn/tools/kumascript/index.html b/files/ko/mdn/tools/kumascript/index.html new file mode 100644 index 0000000000..329f2b3762 --- /dev/null +++ b/files/ko/mdn/tools/kumascript/index.html @@ -0,0 +1,472 @@ +--- +title: KumaScript +slug: MDN/Tools/KumaScript +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - NeedsContent + - NeedsTranslation + - Site-wide + - TopicStub +translation_of: MDN/Tools/KumaScript +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">On the <a href="/en-US/docs/MDN/Kuma">Kuma</a> platform that powers MDN, the template system for automating aspects of content on the wiki is called <a class="link-https" href="https://github.com/mdn/kumascript">KumaScript</a>. KumaScript is powered by server-side JavaScript, implemented using <a class="external" href="https://nodejs.org/en/">Node.js</a>.</span> This article provides basic information on how to use KumaScript.</p> + +<p>For a detailed overview and Q&A of KumaScript, watch the MDN dev team's <a href="https://vreplay.mozilla.com/replay/showRecordDetails.html?sortBy=date&viewCount=1&currentPage=1&groupBy=combo&roomFilter=&usernameFilter=&searchFilter=&usernameFullFilter=&myManager=-1&adminManager=0&webCast=0&command=&recId=1082&auxMessage=&auxMessage1=&lang=en&langChanged=&tenantFilter=&securityTab=">KumaScript Fireside Chat</a> (the meeting starts at 10 minutes into the video). KumaScript replaced DekiScript, which was the template language for MindTouch, the previous platform used by MDN.</p> + +<h3 id="What_is_KumaScript">What is KumaScript?</h3> + +<ul> + <li>A way to reuse and localize content that appears repeatedly between documents (e.g., compatibility labels, section navigation, warning banners).</li> + <li>A way to build documents out of content pulled from other documents.</li> + <li>A way to fetch and include content from other web sites and services (e.g., Bugzilla).</li> +</ul> + +<h3 id="What_KumaScript_is_not">What KumaScript is not</h3> + +<ul> + <li>KumaScript does not support interactive scripting of the kind that can accept form submissions.</li> + <li>KumaScript does not have access to a database, files, or any other way to store information persistently.</li> + <li>KumaScript does not support site personalization based on the user currently logged in.</li> + <li>KumaScript does not have access to user information, only to the content and metadata of a wiki page being viewed.</li> +</ul> + +<h2 id="Basics">Basics</h2> + +<p>KumaScript is used on MDN in <a href="https://github.com/mde/ejs">embedded JavaScript templates</a>. These templates can be invoked in document content by any MDN author, through the use of macros.</p> + +<p>A script in KumaScript is a <em>template</em>, and each template is a file in <a href="https://github.com/mdn/kumascript/tree/master/macros">the macros directory of the KumaScript repository</a> on Github. A template looks like this:</p> + +<pre class="brush: js no-line-numbers notranslate"><% for (var i = 0; i < $0; i++) { %> + Hello #<%= i %> +<% } %></pre> + +<p>Invoking a template is done with a <em>macro</em>, which can be used anywhere in any wiki content. A macro looks like this:</p> + +<pre class="brush: none no-line-numbers notranslate">\{{hello(3)}}</pre> + +<p>The output of the macro looks like this:</p> + +<pre class="brush: html no-line-numbers notranslate">Hello #0 +Hello #1 +Hello #2</pre> + +<h3 id="Macro_syntax">Macro syntax</h3> + +<p>KumaScript templates are invoked in document content with macros, like this:</p> + +<pre class="brush: none no-line-numbers notranslate">\{{templateName("arg0", "arg1", ..., "argN")}}</pre> + +<p>Macro syntax consists of these rules:</p> + +<ul> + <li>Macros start and end with <code>\{{</code> and <code>\}}</code> characters.</li> + <li>The first part of the macro is the name of a template. The lowercase value of this name should match the lowercase value of one of the filenames under <a href="https://github.com/mdn/kumascript/tree/master/macros">the macros directory of KumaScript</a>.</li> + <li>A template can accept parameters, and this parameter list starts and ends with parentheses.</li> + <li>All non-numeric parameters must be in quotes. Numbers can be left unquoted.</li> +</ul> + +<h4 id="Using_JSON_as_a_macro_parameter">Using JSON as a macro parameter</h4> + +<p>As a semi-experimental feature (not guaranteed to work), you can supply a JSON object for the first and only parameter, like so:</p> + +<pre class="brush: none no-line-numbers notranslate">\{{templateName(<code class="language-json">{ "Alpha": "one", "Beta": ["a", "b", "c"], "Foo": "https:\/\/mozilla.org\/" }</code>)}}</pre> + +<p>The data from this macro is available in template code as an object in the <code class="language-javascript">$0</code> argument (e.g., <code>$0.Alpha</code>, <code>$0.Beta</code>, <code>$0.Foo</code>). This also allows you to express complex data structures in macro parameters that are hard or impossible to do with a simple list of parameters.</p> + +<p>Note that this parameter style is very picky — it must adhere to <a href="https://json.org/">JSON syntax</a> exactly, which has some requirements about escaping characters that are easy to miss (e.g., all forward slashes are escaped). When in doubt, <a href="https://jsonlint.com/">try running your JSON through a validator</a>.</p> + +<h4 id="How_to_write_in_text">How to write "\{{" in text</h4> + +<p>Since the character sequence "<code>\{{</code>" is used to indicate the start of a macro, this can be troublesome if you actually just want to use "<code>\{{</code>" and "<code>}}</code>" in a page. It will probably produce <code>DocumentParsingError</code> messages.</p> + +<p>In this case, you can escape the first brace with a backslash, like so: <code>\\{{</code></p> + +<h3 id="Template_syntax">Template syntax</h3> + +<p>Each KumaScript template is a file under <a href="https://github.com/mdn/kumascript/tree/master/macros">the macros directory of KumaScript</a>. You create and edit these files as you would the files of any open-source project on GitHub (see <a href="https://github.com/mdn/kumascript">the KumaScript README</a> for more information).</p> + +<p>KumaScript templates are processed by an <a href="https://ejs.co">embedded JavaScript template engine</a> with a few simple rules:</p> + +<ul> + <li>Within a template, the parameters passed in from the macro are available as the variables <code>$0</code>, <code>$1</code>, <code>$2</code>, and so on. The entire list of parameters is also available in a template as the variable <code>arguments</code>.</li> + <li>Most text is treated as output and included in the output stream.</li> + <li>JavaScript variables and expressions can be inserted into the output stream with these blocks: + <ul> + <li><code class="language-ejs"><%= expr %></code> — the value of a JavaScript expression is escaped for HTML before being included in output (e.g., characters like <code><</code> and <code>></code> are turned into <code>&lt;</code> and <code>&gt;</code>).</li> + <li><code class="language-ejs"><%- expr %></code> — the value of a JavaScript expression is included in output without any escaping. (Use this if you want to dynamically build markup or use the results of another template that may include markup.)</li> + <li>It is an error to include semicolons inside these blocks.</li> + </ul> + </li> + <li>Anything inside a <code class="language-ejs"><% %></code> block is interpreted as JavaScript. This can include loops, conditionals, etc.</li> + <li>Nothing inside a <code class="language-ejs"><% %></code> block can ever contribute to the output stream. But, you can transition from JS mode to output mode using <code><% %></code>—for example: + <pre class="brush: js notranslate"><% for (var i = 0; i < $0; i++) { %> + Hello #<%= i %> +<% } %></pre> + + <p>Note how the JavaScript code is contained in <code class="language-ejs"><% ... %></code>, and output happens in the space between <code class="language-ejs">%> ... <%</code>. The <code>for</code> loop in JS can begin with one <code class="language-ejs"><% %></code> block, transition to output mode, and finish up in a second <code class="language-ejs"><% %></code> JS block.</p> + </li> + <li>For more details on EJS syntax, <a href="https://ejs.co">check out the upstream module documentation</a>.</li> +</ul> + +<h3 id="Tips">Tips</h3> + +<p>You can see a list of macros and how they are used on MDN on the <a href="/en-US/dashboards/macros">macros dashboard</a>.</p> + +<h2 id="Advanced_Features">Advanced Features</h2> + +<p>Beyond the basics, the KumaScript system offers some advanced features.</p> + +<h3 id="Environment_variables">Environment variables</h3> + +<p>When the wiki makes a call to the KumaScript service, it passes along some context on the current document that KumaScript makes available to templates as variables:</p> + +<dl> + <dt><code>env.path</code></dt> + <dd>The path to the current wiki document</dd> + <dt><code>env.url</code></dt> + <dd>The full URL to the current wiki document</dd> + <dt><code>env.id</code></dt> + <dd>A short, unique ID for the current wiki document</dd> + <dt><code>env.files</code></dt> + <dd>An array of the files attached to the current wiki document; each object in the array is as described under {{ anch("File objects") }} below</dd> + <dt><code>env.review_tags</code></dt> + <dd>An array of the review tags on the article ("technical", "editorial", etc.)</dd> + <dt><code>env.locale</code></dt> + <dd>The locale of the current wiki document</dd> + <dt><code>env.title</code></dt> + <dd>The title of the current wiki document</dd> + <dt><code>env.slug</code></dt> + <dd>The URL slug of the current wiki document</dd> + <dt><code>env.tags</code></dt> + <dd>An array list of tag names for the current wiki document</dd> + <dt><code>env.modified</code></dt> + <dd>Last modified timestamp for the current wiki document</dd> + <dt><code>env.cache_control</code></dt> + <dd><code>Cache-Control</code> header sent in the request for the current wiki document, useful in deciding whether to invalidate caches</dd> +</dl> + +<h4 id="File_objects">File objects</h4> + +<p>Each file object has the following fields:</p> + +<dl> + <dt><code>title</code></dt> + <dd>The attachment's title</dd> + <dt><code>description</code></dt> + <dd>A textual description of the current revision of the file</dd> + <dt><code>filename</code></dt> + <dd>The file's name</dd> + <dt><code>size</code></dt> + <dd>The size of the file in bytes</dd> + <dt><code>author</code></dt> + <dd>The username of the person who uploaded the file</dd> + <dt><code>mime</code></dt> + <dd>The MIME type of the file</dd> + <dt><code>url</code></dt> + <dd>The URL at which the file can be found</dd> +</dl> + +<h4 id="Working_with_tag_lists">Working with tag lists</h4> + +<p>The <code>env.tags</code> and <code>env.review_tags</code> variables return arrays of tags. You can work with these in many ways, of course, but here are a couple of suggestions.</p> + +<h5 id="Looking_to_see_if_a_specific_tag_is_set">Looking to see if a specific tag is set</h5> + +<p>You can look to see if a specific tag exists on a page like this:</p> + +<pre class="brush: js notranslate">if (env.tags.indexOf("tag") != −1) { + // The page has the tag "tag" +} +</pre> + +<h5 id="Iterating_over_all_the_tags_on_a_page">Iterating over all the tags on a page</h5> + +<p>You can also iterate over all the tags on a page, like this:</p> + +<pre class="brush: js notranslate">env.tag.forEach(function(tag) { + // do whatever you need to do, such as: + if (tag.indexOf("a") == 0) { + // this tag starts with "a" - woohoo! + } +});</pre> + +<h3 id="APIs_and_Modules">APIs and Modules</h3> + +<p>KumaScript offers some built-in methods and APIs for KumaScript macros. Macros can also use <code>module.exports</code> to export new API methods.</p> + +<p>API changes require updating the KumaScript engine or macros via a pull request to the <a href="https://github.com/mdn/kumascript">KumaScript repository</a>.</p> + +<h4 id="Built-in_methods">Built-in methods</h4> + +<p>This manually-maintained documentation is likely to fall out of date with the code. With that in mind, <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/lib/kumascript/api.js#L175" title="https://github.com/mdn/kumascript/blob/master/lib/kumascript/api.js#L208">you can always check out the latest state of built-in APIs in the KumaScript source</a>. But here is a selection of useful methods exposed to templates:</p> + +<dl> + <dt><code class="language-javascript">md5(string)</code></dt> + <dd>Returns an MD5 hex digest of the given string.</dd> + <dt><code class="language-javascript">template("name", ["arg0", "arg1", ..., "argN"])</code></dt> + <dd> + <p>Executes and returns the result of the named template with the given list of parameters.</p> + + <p>Example: <code class="language-javascript"><%- template("warning", ["foo", "bar", "baz"]) %></code>.</p> + + <p>Example using the <code>DOMxRef</code> macro: <code class="language-javascript"><%- template("DOMxRef", ["Event.bubbles", "bubbles"]) %></code>.</p> + + <p>This is a JavaScript function. So, if one of the parameters is an arg variable like $2, do not put it in quotes. Like this: <code class="language-javascript"><%- template("warning", [$1, $2, "baz"]) %></code>. If you need to call another template from within a block of code, do not use <code><%</code> ... <code>%></code>. Example: <code class="language-javascript">myvar = "<li>" + template("LXRSearch", ["ident", "i", $1]) + "</li>";</code></p> + </dd> + <dt><code class="language-javascript">require(name)</code></dt> + <dd>Loads another template as a module; any output is ignored. Anything assigned to <code class="language-javascript">module.exports</code> in the template is returned.</dd> + <dd>Used in templates like so: <code class="language-javascript"><% const my_module = require('MyModule'); %></code>.</dd> + <dt><code class="language-javascript">cacheFn(key, timeout, function_to_cache)</code></dt> + <dd>Using the given key and cache entry lifetime, cache the results of the given function. Honors the value of <code>env.cache_control</code> to invalidate cache on <code>no-cache</code>, which can be sent by a logged-in user hitting shift-refresh.</dd> + <dt><code class="language-javascript">request</code></dt> + <dd>Access to <a class="link-https" href="https://github.com/mikeal/request" title="https://github.com/mikeal/request"><code>mikeal/request</code></a>, a library for making HTTP requests. Using this module in KumaScript templates is not yet very friendly, so you may want to wrap usage in module APIs that simplify things.</dd> + <dt><code class="language-javascript">log.debug(string)</code></dt> + <dd>Outputs a debug message into the script log on the page (i.e. the big red box that usually displays errors).</dd> +</dl> + +<h4 id="Built-in_API_modules">Built-in API modules</h4> + +<p>There are a set of built in API that are automatically loaded and made available to every template by the environment script.</p> + +<p>For the most part, these attempt to provide stand-ins for legacy DekiScript features to ease template migration. But, going forward, these can be used to share common variables and methods between templates:</p> + +<ul> + <li><code>kuma.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/kuma.js">Kuma</a></li> + <li><code>MDN.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/mdn.js">MDN:Common</a></li> + <li><code>page.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/page.js">DekiScript:Page</a></li> + <li><code>string.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/string.js">DekiScript:String</a></li> + <li><code>uri.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/uri.js">DekiScript:Uri</a></li> + <li><code>web.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/web.js">DekiScript:Web</a></li> + <li><code>wiki.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/wiki.js">DekiScript:Wiki</a></li> +</ul> + +<p>You can see the most up to date list of methods under <code>kuma</code> from <a href="https://github.com/mdn/kumascript/blob/master/src/api/kuma.js">the KumaScript source code</a>, but here are a few:</p> + +<dl> + <dt><code class="language-javascript">kuma.inspect(object)</code></dt> + <dd>Renders any JS object as a string, handy for use with <code>log.debug()</code>. See also: <a href="https://nodejs.org/api/util.html#util_util_inspect_object_options">node.js <code class="language-javascript">util.inspect()</code></a>.</dd> + <dt><code class="language-javascript">kuma.htmlEscape(string)</code></dt> + <dd>Escapes the characters <code>&, <, >, "</code> to <code>&amp, &lt;, &gt;, &quot;</code>, respectively.</dd> + <dt><code class="language-javascript">kuma.url</code></dt> + <dd>See also: <a href="http://nodejs.org/api/url.html">node.js <code>url</code> module</a>.</dd> + <dt><code class="language-javascript">kuma.fetchFeed(url)</code></dt> + <dd>Fetch an RSS feed and parse it into a JS object. See also: <a href="https://github.com/mdn/kumascript/blob/master/macros/InsertFeedLinkList.ejs"><code>InsertFeedLinkList</code></a></dd> +</dl> + +<h4 id="Creating_modules">Creating modules</h4> + +<p>Using the built-in <code>require()</code> method, you can load a template as a module to share common variables and methods between templates. A module can be defined in a template like this:</p> + +<pre class="brush: js notranslate"><% +module.exports = { + add: function (a, b) { + return a + b; + } +} +%></pre> + +<p>Assuming this template is saved under <a href="https://github.com/mdn/kumascript/tree/master/macros">https://github.com/mdn/kumascript/tree/master/macros</a> as <code>MathLib.ejs</code>, you can use it in another template like so:</p> + +<pre class="brush: js notranslate"><% +var math_lib = require("MathLib"); +%> +The result of 2 + 2 = <%= math_lib.add(2, 2) %></pre> + +<p>And, the output of this template will be:</p> + +<pre class="brush: html no-line-numbers notranslate">The result of 2 + 2 = 4</pre> + +<h2 id="Tips_and_caveats">Tips and caveats</h2> + +<h3 id="Debugging">Debugging</h3> + +<p>A useful tip when debugging. You can use the <code>log.debug()</code> method to output text to the scripting messages area at the top of the page that's running your template. Note that you need to be really sure to remove these when you're done debugging, as they're visible to all users! To use it, just do something like this:</p> + +<pre class="brush: js no-line-numbers notranslate"><%- log.debug("Some text goes here"); %></pre> + +<p>You can, of course, create more complex output using script code if it's helpful.</p> + +<h3 id="Caching">Caching</h3> + +<p>KumaScript templates are heavily cached to improve performance. For the most part, this works great to serve up content that doesn't change very often. But, as a logged-in user, you have two options to force a page to be regenerated, in case you notice issues with scripting:</p> + +<ul> + <li>Hit Refresh in your browser. This causes KumaScript to invalidate its cache for the content on the current page by issuing a request with a <code>Cache-Control: max-age=0</code> header.</li> + <li>Hit Shift-Refresh in your browser. This causes KumaScript to invalidate cache for the current page, as well as for any templates or content used by the current page by issuing a request with a <code>Cache-Control: no-cache</code> header.</li> +</ul> + +<h3 id="Using_search_keywords_to_open_template_pages">Using search keywords to open template pages</h3> + +<p>When using templates, it's common to open the template's code in a browser window to review the comments at the top, which are used to document the template, its parameters, and how to use it properly. To quickly access templates, you can create a Firefox <a href="http://kb.mozillazine.org/Using_keyword_searches">search keyword</a>, which gives you a shortcut you can type in the URL box to get to a template more easily.</p> + +<p>To create a search keyword, open the bookmarks window by choosing "Show all bookmarks" in the Bookmarks menu, or by pressing <kbd>Control+Shift+B</kbd> (<kbd>Command+Shift+B</kbd> on Mac). Then from the utility ("Gear") menu in the Library window that appears, choose "New Bookmark...".</p> + +<p>This causes the bookmark editing dialog to appear. Fill that out as follows:</p> + +<dl> + <dt>Name</dt> + <dd>A suitable name for your search keyword; "Open MDN Template" is a good one.</dd> + <dt>Location</dt> + <dd><code>https://github.com/mdn/kumascript/blob/master/macros/%s</code></dd> + <dt>Tags{{Optional_Inline}}</dt> + <dd>A list of tags used to organize your bookmarks; these are entirely optional and what (if any) tags you use is up to you.</dd> + <dt>Keyword</dt> + <dd>The shortcut text you wish to use to access the template. Ideally, this should be something short and quick to type, such as simply "t" or "mdnt".</dd> + <dt>Description{{Optional_Inline}}</dt> + <dd>A suitable description explaining what the search keyword does.</dd> +</dl> + +<p>The resulting dialog looks something like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14432/Screen%20Shot%202016-11-28%20at%203.08.39%20PM.png" style="height: 289px; width: 500px;"></p> + +<p>Then click the "Add" button to save your new search keyword. From then on, typing your keyword, then a space, then the name of a macro will open that macro in your current tab. So if you used "t" as the keyword, typing <kbd>t ListSubpages</kbd> will show you the page at {{TemplateLink("ListSubpages")}}.</p> + +<h2 id="Cookbook">Cookbook</h2> + +<p>This section will list examples of common patterns for templates used on MDN, including samples of legacy DekiScript templates and their new KumaScript equivalents.</p> + +<h3 id="Force_templates_used_on_a_page_to_be_reloaded">Force templates used on a page to be reloaded</h3> + +<p>It bears repeating: To force templates used on a page to be reloaded after editing, hit Shift-Reload. Just using Reload by itself will cause the page contents to be regenerated, but using cached templates and included content. A Shift-Reload is necessary to invalidate caches beyond just the content of the page itself.</p> + +<h3 id="Recovering_from_Unknown_Error">Recovering from "Unknown Error"</h3> + +<p>Sometimes, you'll see a scripting message like this when you load a page:</p> + +<pre class="brush: none no-line-numbers notranslate">Kumascript service failed unexpectedly: <class 'httplib.BadStatusLine'></pre> + +<p>This is probably a temporary failure of the KumaScript service. If you Refresh the page, the error may disappear. If that doesn't work, try a Shift-Refresh. If, after a few tries, the error persists - <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&format=itrequest">file an IT bug</a> for Mozilla Developer Network to ask for an investigation.</p> + +<h3 id="Broken_wiki.languages_macros">Broken wiki.languages() macros</h3> + +<p>On some pages, you'll see a scripting error like this:</p> + +<pre class="brush: none; no-line-numbers notranslate">Syntax error at line 436, column 461: Expected valid JSON object as the parameter of the preceding macro but...</pre> + +<p>If you edit the page, you'll probably see a macro like this at the bottom of the page:</p> + +<pre class="brush: none no-line-numbers notranslate">\{{ wiki.languages(<code class="language-json">{ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }</code>) }}</pre> + +<p>To fix the problem, just delete the macro. Or, replace the curly braces on either side with HTML comments <code><!-- --></code> to preserve the information, like so:</p> + +<pre class="brush: html no-line-numbers notranslate"><!-- wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) --></pre> + +<p>Because Kuma supports localization differently, these macros aren't actually needed any more. But, they've been left intact in case we need to revisit the relationships between localized pages. Unfortunately, it seems like migration has failed to convert some of them properly.</p> + +<h3 id="Finding_the_Current_Pages_Language">Finding the Current Page's Language</h3> + +<p>In KumaScript, the locale of the current document is exposed as an environment variable:</p> + +<pre class="brush: js no-line-numbers notranslate">const lang = env.locale;</pre> + +<p>The <code>env.locale</code> variable should be reliable and defined for every document.</p> + +<h3 id="Reading_the_contents_of_a_page_attachment">Reading the contents of a page attachment</h3> + +<p>You can read the contents of an attached file by using the <code>mdn.getFileContent()</code> function, like this:</p> + +<pre class="brush: js notranslate"><% + let contents = mdn.getFileContent(fileUrl); + // ... do stuff with the contents ... +%> +</pre> + +<p>or</p> + +<pre class="brush: js no-line-numbers notranslate"><%- mdn.getFileContent(fileObject); %> +</pre> + +<p>In other words, you may specify either the URL of the file to read or as a file object. The file objects for a page can be accessed through the array <code>env.files</code>. So, for example, to embed the contents of the first file attached to the article, you can do this:</p> + +<pre class="brush: js no-line-numbers notranslate"><%- mdn.getFileContent(env.files[0]); %> +</pre> + +<div class="blockIndicator note"> +<p><strong>Note:</strong> You probably don't want to try to embed the contents of a non-text file this way, as the raw contents would be injected as text. This is meant to let you access the contents of text attachments.</p> +</div> + +<p>If the file isn't found, an empty string is returned. There is currently no way to tell the difference between an empty file and a nonexistent one. But if you're putting empty files on the wiki, you're doing it wrong.</p> + +<h3 id="Localizing_template_content" name="Localizing_template_content">テンプレートのローカライズ</h3> + +<p>Templates are not translated like wiki pages, rather any single template might be used for any number of locales.</p> + +<p>So the main way to output content tailored to the current document locale is to pivot on the value of <code>env.locale</code>. There are many ways to do this, but a few patterns are common in the conversion of legacy DekiScript templates:</p> + +<h4 id="Ifelse_blocks_in_KumaScript">If/else blocks in KumaScript</h4> + +<p>The KumaScript equivalent of this can be achieved with simple if/else blocks, like so:</p> + +<pre class="brush: js notranslate"><% if ("fr" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/fr/docs/Référence_CSS/Extensions_Mozilla">Référence CSS: Extensions Mozilla</a> +<% } else if ("ja" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/ja/docs/CSS_Reference/Mozilla_Extensions">CSS リファレンス: Mozilla 拡張仕様</a> +<% } else if ("pl" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/pl/docs/Dokumentacja_CSS/Rozszerzenia_Mozilli">Dokumentacja CSS: Rozszerzenia Mozilli</a> +<% } else if ("de" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/de/docs/CSS_Referenz/Mozilla_CSS_Erweiterungen">CSS Referenz: Mozilla Erweiterungen</a> +<% } else { %> +<%- template("CSSRef") %> « <a href="/en-US/docs/CSS_Reference/Mozilla_Extensions">CSS Reference: Mozilla Extensions</a> +<% } %></pre> + +<p>Depending on what text editor is your favorite, you may be able to copy & paste from the browser-based editor and attack this pattern with a series of search/replace regexes to get you most of the way there.</p> + +<p>My favorite editor is MacVim, and a series of regexes like this does the bulk of the work with just a little manual clean up following:</p> + +<pre class="brush: none notranslate">%s#<span#^M<span#g +%s#<span lang="\(.*\)" .*>#<% } else if ("\1" == env.locale) { %>#g +%s#<span class="script">template.CSSxRef(#<%- template("CSSxRef", [# +%s#)</span> </span>#]) %> +</pre> + +<p>Your mileage may vary, and patterns change slightly from template to template. That's why the migration script was unable to just handle this automatically, after all.</p> + +<h4 id="String_variables_and_switch">String variables and switch</h4> + +<p>Rather than switch between full chunks of markup, you can define a set of strings, switch them based on locale, and then use them to fill in placeholders in a single chunk of markup:</p> + +<pre class="brush: js notranslate"><% +var s_title = 'Firefox for Developers'; +switch (env.locale) { + case 'de': + s_title = "Firefox für Entwickler"; + break; + case 'fr': + s_title = "Firefox pour les développeurs"; + break; + case 'es': + s_title = "Firefox para desarrolladores"; + break; +}; +%> +<span class="title"><%= s_title %></span></pre> + +<h4 id="Use_mdn.localString">Use <code class="language-javascript">mdn.localString()</code></h4> + +<p>A recent addition to the <code>MDN:Common</code> module is <code class="language-javascript">mdn.localString()</code>, used like this:</p> + +<pre class="brush: js notranslate"><% +var s_title = mdn.localString({ + "en-US": "Firefox for Developers", + "de": "Firefox für Entwickler", + "es": "Firefox para desarrolladores" +}); +%> +<span class="title"><%= s_title %></span></pre> + +<p>This is more concise than the switch statement, and may be a better choice where a single string is concerned. However, if many strings need to be translated (e.g., as in {{TemplateLink("CSSRef")}}), a switch statement might help keep all the strings grouped by locale and more easily translated that way.</p> + +<p>When the object does not have the appropriate locale, the value of "en-US" is used as the initial value.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="https://github.com/mdn/kumascript">KumaScript source code</a></li> + <li><a href="https://wiki.mozilla.org/MDN/Kuma">Kuma wiki</a></li> +</ul> diff --git a/files/ko/mdn/tools/kumascript/troubleshooting/index.html b/files/ko/mdn/tools/kumascript/troubleshooting/index.html new file mode 100644 index 0000000000..ab72f466f1 --- /dev/null +++ b/files/ko/mdn/tools/kumascript/troubleshooting/index.html @@ -0,0 +1,59 @@ +--- +title: KumaScript 에러 해결하기 +slug: MDN/Tools/KumaScript/Troubleshooting +translation_of: MDN/Tools/KumaScript/Troubleshooting +--- +<div>{{MDNSidebar}}</div> + +<div class="summary"> +<p><a href="/en-US/docs/MDN/Kuma/Introduction_to_KumaScript"> </a>빨갛고 무서운 상자 안에 든 <a href="/en-US/docs/MDN/Kuma/Introduction_to_KumaScript">KumaScript</a> 에러는 매우 보기 불편합니다. 하지만 다행히도, MDN 계정이 있다면 누구나 문서를 편집해 이 문제를 해결할 수 있어요. When a page has an error it gets added to the list of <a href="/docs/with-errors">documents with errors</a>. Site editors go through this list regularly to find and fix errors. This article details the four types of KumaScript error, and some steps you can take to fix them.</p> +</div> + +<h2 id="DocumentParsingError">DocumentParsingError</h2> + +<p><code>DocumentParsingError</code> errors appear when KumaScript has trouble understanding something in the document itself. The most common cause is a syntax error in a <a href="/en-US/docs/MDN/Contribute/Content/Macros">macro</a>.</p> + +<p>Check for:</p> + +<dl> + <dt>Use of curly braces without intending to call a macro.</dt> + <dd>If you need to write \{ in a document without calling a macro you can escape it with a \ like this: <code>\\{</code></dd> + <dt>Use of a special character in a macro parameter.</dt> + <dd>If you need to use a " or a \ inside of a macro parameter they can be escaped with a \ like this: <code>\\</code> or <code>\"</code></dd> + <dt>Missing commas between macro parameters.</dt> + <dd>Macro parameters need to be delimited by a comma (,) but not at the end of the list of parameters; for example <code>\{\{anch("top", "Back to top")}}</code>.</dd> + <dt>HTML tags appearing inside a macro call</dt> + <dd>If you apply styling to a macro, it will often break because, for example, a <code></code></code> tag may have appeared inside the macro code in the source code. Check the source view to see what's there, and remove any unnecessary styling.</dd> +</dl> + +<ul> +</ul> + +<h2 id="TemplateLoadingError">TemplateLoadingError</h2> + +<p><code>TemplateLoadingError</code> errors appear when KumaScript has trouble finding which <a href="/en-US/docs/MDN/Contribute/Content/Macros">macro</a> to include on a page.</p> + +<p>Check for:</p> + +<dl> + <dt>Misspelling of macro names or renamed macros.</dt> + <dd>You can look at the list of known macros in the <a href="https://github.com/mdn/kumascript/tree/master/macros">Github repo</a>.</dd> +</dl> + +<div class="note"> +<p><strong>Tip:</strong> You can make it quick and easy to jump to a specific macro by adding a <a href="http://kb.mozillazine.org/Using_keyword_searches">search keyword</a> to Firefox. See {{SectionOnPage("/en-US/docs/MDN/Contribute/Tools/KumaScript", "Using search keywords to open template pages")}} for a step-by-step guide to creating the search keyword for this.</p> +</div> + +<h2 id="TemplateExecutionError">TemplateExecutionError</h2> + +<p><code>TemplateExecutionError</code> errors appear when KumaScript encounters an error in the macro. These errors can only be fixed by admin users and need to be reported as bugs.</p> + +<p>Before reporting an error check to see that it hasn't already been fixed. You can do this by forcing KumaScript to give you a fresh copy of the page by holding down <kbd>Shift</kbd> while you refresh the page (<kbd>Shift</kbd> + <kbd>Ctrl</kbd> + <kbd>R</kbd> on Windows/Linux, <kbd>Shift</kbd> + <kbd>Cmd</kbd> + <kbd>R</kbd> on Mac).</p> + +<p>If the error persists, <a href="https://bugzilla.mozilla.org/form.doc">report a bug</a>, including the URL of the page and the text of the error.</p> + +<h2 id="Error_Unknown">Error & Unknown</h2> + +<p>This is the category errors end up in if they are not one of the other kinds of error.</p> + +<p>Check for fixes and report persistent bugs like described under <a href="#TemplateExecutionError">TemplateExecutionError</a>.</p> diff --git a/files/ko/mdn/tools/페이지_재생성/index.html b/files/ko/mdn/tools/페이지_재생성/index.html new file mode 100644 index 0000000000..2b75d2508f --- /dev/null +++ b/files/ko/mdn/tools/페이지_재생성/index.html @@ -0,0 +1,34 @@ +--- +title: 페이지 재생성 +slug: MDN/Tools/페이지_재생성 +tags: + - Guide + - MDN Meta + - Page-level + - Tools +translation_of: MDN/Tools/Page_regeneration +--- +<div>{{MDNSidebar}}</div><p>MDN 사이트는 성능상의 이유로 페이지를 캐시합니다. 그 결과, 당신이 페이지에 저장한 변경 사항이 다음 번 페이지 새로 고침할 때 나타나지 않을 수 있습니다. 자주, 항상은 아니지만, 배너가 페이지 업데이트가 진행 중임을 알리는 페이지에 나타납니다. 당신은 서버에서 페이지를 새로 고침하기 위해 브라우저에 "강제 새로 고침"을 할 수 있지만, 이는 서버의 업데이트가 끝나지 않았다면 효과가 없을 지도 모릅니다.</p> + +<p>일부 페이지(특히 첫방문landing 페이지)는 자동으로 생성하고 콘텐츠를 업데이트하기 위해 매크로를 사용합니다. 첫방문 페이지의 경우, 매크로는 글쓴이가 손수 추가할 필요 없이 새 글이 자동으로 페이지에 나열되게 합니다. 이는 오랜 공헌자에게는 편리하고, 새로 온 이들은 사이트 계층구조에 자신의 글을 링크하는 법을 모르기에 그들의 작업을 셔플에서 잃는 것을 막는 데 도움이 됩니다.</p> + +<p>이는 (예를 들어, {{TemplateLink("Page")}} 매크로를 써서) 한 페이지의 콘텐츠를 다른 페이지로 삽입(transcluding)할 때도 사용할 수 있습니다.</p> + +<p><span class="seoSummary">MDN은 성능상의 이유로 렌더링된 콘텐츠를 캐시하기 때문에, (매크로 출력이나 삽입transcluded 페이지 같은) 원 저작물(source material)에 더해진 변경 사항은 자동으로 페이지에 반영되지 않습니다. 그러한 원 저작물에 자주 변경이 예상되는 경우, 자동 페이지 재생성 활성화를 고려할 수 있습니다.</span></p> + +<p>자동 재생성을 활성화하기 위해서:</p> + +<ol> + <li>편집 모드 진입을 위해 페이지 상의 <strong>편집</strong> 버튼 클릭.</li> + <li>페이지 제목 아래, 페이지 제목 근처에 위치한 <strong>페이지 제목과 속성 편집</strong> 클릭. 페이지 메타데이터 필드가 나타남.</li> + <li><strong>렌더링 최대 수명</strong>값을 설정. 이 값은 캐시된 페이지의 매크로 재실행을 포함하여, 재빌드되는 일정을 결정합니다. 보통, 우리는 여기에 4내지 8시간을 사용합니다. 기술의 문서화가 빠르게 바뀌는 경우, 더 작은 수를 선택할 수 있습니다.</li> + <li>페이지에 변경 사항을 저장. 리비전 코멘트에 "렌더링 최대 수명을 4시간으로 설정"과 같이, 당신이 작업한 내용을 설명하는 것은 좋은 습관입니다. </li> +</ol> + +<p>페이지는 당신이 지정한 일정대로 자동으로 재성성됩니다.</p> + +<div class="note"> +<p><strong>주의:</strong> "페이지 제목과 속성 편집" 옵션은 새 페이지를 만들 때는 이용할 수 없습니다. 첫 번째 저장 이후로 편집기를 다시 열어야 합니다.</p> +</div> + +<p> </p> diff --git a/files/ko/mdn/user_guide/index.html b/files/ko/mdn/user_guide/index.html new file mode 100644 index 0000000000..5abcd75cc9 --- /dev/null +++ b/files/ko/mdn/user_guide/index.html @@ -0,0 +1,11 @@ +--- +title: MDN 사용자 가이드 +slug: MDN/User_guide +tags: + - 모질라 개발자 네트워크 + - 사용자 가이드 +translation_of: MDN/Tools +--- +<div>{{MDNSidebar}}</div><p>모질라 개발자 네트워크 (이하 MDN) 사이트는, (파이어폭스 및 파이어폭스 운영체제 개발자 뿐 아니라) 웹 개발자를 위한 문서 및 샘플 코드를 찾고, 읽고, 기여하는 고급 시스템입니다. MDN 사용자 가이드는 필요한 문서를 찾도록 MDN을 이용하는 방법을, 원한다면 좀 더 좋은, 더 광범위하고, 더 완전한 자료를 만들도록 돕는 방법을 열거하는 항목을 제공합니다.</p> + +<p>{{LandingPageListSubpages}}</p> |