MDN 웹 문서에 기여하기

MDN Web Docs는 12년 넘게 웹 플랫폼을 문서화해 왔으며 현재 Google, Microsoft 및 Samsung의 구성원과 Firefox를 대표하는 구성원과 함께 기여 및 자문 위원회와 함께 크로스 플랫폼 노력입니다. MDN의 기본은 문서를 만들고 유지 관리하는 데 도움이 되는 웹 커뮤니티와 함께 ​​엄청난 커뮤니티 노력이라는 것입니다. 이 기사에서, 나는 당신이 MDN에 기여할 수 있는 곳과 정확히 어떻게 하면 되는지에 대한 몇 가지 지침을 제공할 것입니다.

이전에 오픈 소스 프로젝트에 기여한 적이 없다면 MDN이 시작하기에 좋은 곳입니다. 필요한 기술은 복사 편집, 영어에서 다른 언어로 번역, 대화형 예제를 만들기 위한 HTML 및 CSS 기술 또는 브라우저 호환성 데이터 업데이트를 위한 브라우저 호환성에 대한 관심 범위입니다. 기여하기 위해 많은 양의 코드를 작성할 필요가 없습니다. 매우 간단하며 이 문서가 유용하다는 것을 알게 된 경우 커뮤니티에 보답할 수 있는 훌륭한 방법입니다.

문서 페이지에 기여하기

기여하고 싶은 첫 번째 장소는 MDN 문서 자체입니다. MDN은 위키이므로 CSS, HTML, JavaScript 또는 MDN에서 다루는 웹 플랫폼의 다른 부분에 대한 문서를 수정하거나 추가하여 로그인하고 도움을 시작할 수 있습니다.

편집을 시작하려면 GitHub를 사용하여 로그인해야 합니다. 위키에서와 같이 페이지의 모든 편집자가 나열되며 이 섹션에서는 GitHub 사용자 이름을 사용합니다. MDN 기여자가 페이지 하단에 나열되어 있는 페이지를 보면 아래 이미지는 CSS 그리드 레이아웃에서 페이지에 대한 현재 기여자를 보여줍니다.

무엇을 편집할 수 있습니까?

편집자로서 고려할 수 있는 사항은 명백한 오타 및 문법 오류를 수정하는 것입니다. 당신이 훌륭한 교정자이자 복사자라면 발견한 철자나 기타 오류를 수정하여 문서의 가독성을 향상시킬 수 있습니다.

또한 기술적인 오류를 발견하거나 사양이 변경된 곳과 업데이트 또는 설명이 유용한 곳을 발견할 수도 있습니다. MDN이 다루는 광범위한 웹 플랫폼 기능과 변화율로 인해 무언가를 발견하면 수정하기가 매우 쉽습니다.

추가 정보를 추가해야 하는 특정 지식을 사용할 수 있습니다. 예를 들어 Eric Bailey는 여러 페이지에 접근성 문제 섹션을 추가하고 있습니다. 이것은 우리가 어떤 것을 사용할 때 생각해야 할 점을 강조하기 위한 기발한 시도입니다.

페이지에 추가할 수 있는 또 다른 위치는 "참조 항목" 링크를 추가하는 것입니다. MDN의 다른 부분이나 외부 리소스에 대한 링크일 수 있습니다. 외부 자원을 추가할 때 이는 해당 문서에서 설명하는 속성, 요소 또는 기술과 관련성이 높아야 합니다. 좋은 후보는 해당 기능을 사용하는 방법을 보여주는 튜토리얼이 될 것입니다. 이는 독자가 정보를 검색하는 데 중요한 다음 단계를 제공할 것입니다.

문서를 편집하는 방법?

로그인하면 MDN의 페이지에 편집 링크가 표시되며 이를 클릭하면 콘텐츠 편집을 위한 WYSIWYG 편집기로 이동합니다. 처음 몇 가지 수정 사항은 작은 변경 사항일 가능성이 높으며, 이 경우 코를 따라 텍스트를 수정할 수 있어야 합니다. 광범위하게 편집하는 경우 먼저 스타일 가이드를 살펴보는 것이 좋습니다. WYSIWYG Editor 사용 가이드도 있습니다.

편집한 후에는 미리보기한 다음 게시할 수 있습니다. 게시하기 전에 추가한 내용과 개정 설명 필드를 사용하는 이유를 설명하는 것이 좋습니다.

언어 번역

영어를 모국어로 사용하는 사람들은 웹에서 정보를 얻을 때 매우 운이 좋았습니다. 우리가 원하는 거의 모든 정보를 모국어로 얻을 수 있다는 점입니다. 영어 페이지를 다른 언어로 번역할 수 있다면 MDN 웹 문서를 번역하여 이 모든 정보를 더 많은 사람들이 사용할 수 있도록 도울 수 있습니다.

페이지에서 언어 아이콘을 클릭하면 해당 정보가 번역된 언어를 볼 수 있으며 MDN 페이지 번역 페이지의 정보에 따라 자신의 번역을 추가할 수 있습니다.

대화형 예제

MDN의 대화형 예제는 grid-area 속성에 대한 것과 같이 MDN의 여러 페이지 상단에서 볼 수 있는 예제입니다.

이 예제를 통해 MDN 방문자는 개발 환경으로 이동하지 않고도 MDN에서 CSS 속성에 대한 다양한 값을 시도하거나 JavaScript 기능을 시도할 수 있습니다. 이러한 예제를 추가하는 프로젝트는 약 1년 동안 진행되었으며, MDN에 대화형 예제 가져오기 게시물에서 현재까지의 프로젝트 및 진행 상황에 대해 읽을 수 있습니다.

이러한 대화식 예제의 콘텐츠는 대화식 예제 GitHub 리포지토리에 있습니다. 예를 들어 grid-area에 대한 예제를 찾으려면 live-examples/css-examples/grid 아래의 해당 리포지토리에서 찾을 수 있습니다. 해당 폴더 아래에 grid-area , HTML 및 CSS 파일에 대한 두 개의 파일이 있습니다.

grid-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.area.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

인터랙티브 예제는 프레임워크가 예제를 선택하고 인터랙티브하게 만들기 위해 몇 가지 표준 클래스와 ID를 사용하는 작은 데모입니다. 공장. 대화형 예제를 추가하거나 편집하려면 먼저 대화형 예제 리포지토리를 분기하고 컴퓨터에 복제한 다음 기여 페이지의 지침에 따라 npm에서 필요한 패키지를 설치하고 로컬에서 예제를 빌드 및 테스트할 수 있습니다.

그런 다음 분기를 만들고 새 예제를 편집하거나 만듭니다. 만족스러우면 대화형 예제 리포지토리에 풀 요청을 보내 예제를 검토하도록 요청하세요. 예제의 일관성을 유지하기 위해 리뷰는 상당히 까다롭지만 변경해야 할 사항을 명확하게 지적해야 합니다. 따라서 예제를 업데이트하고 승인, 병합 및 MDN 페이지에 추가할 수 있습니다.

이제 (JavaScript 예제 외에도) 거의 모든 CSS를 다루므로 MDN은 이제 HTML 예제를 빌드하는 데 도움을 찾고 있습니다. MDN Discourse Forum의 게시물에 시작하는 방법에 대한 지침이 있습니다. 특정 예제를 작업 중임을 나타내는 데 사용할 수 있는 Google 문서와 기타 유용한 정보에 대한 링크를 제공하는 해당 게시물을 확인하십시오.

Interactive Example은 웹 플랫폼을 탐색하는 사람들에게 매우 유용하므로 프로젝트에 추가하는 것이 기여하는 훌륭한 방법입니다. CSS 또는 HTML 예제에 기여하려면 CSS 및 HTML에 대한 지식과 명확한 데모를 생각해낼 수 있는 능력이 필요합니다. 이 마지막 요점은 종종 가장 어려운 부분입니다. 저는 실제로 코드를 작성하는 것보다 많은 CSS 대화형 예제를 만들고 각 속성에 대한 최상의 예제를 생각하는 데 더 많은 시간을 보냈습니다.

브라우저 호환성 데이터

꽤 최근에 MDN 페이지에 나열된 브라우저 호환성 데이터가 브라우저 호환성 프로젝트를 통해 업데이트되기 시작했습니다. 이 프로젝트는 MDN에 호환성 테이블을 표시할 수 있지만 다른 용도로 유용한 데이터가 될 수 있는 JSON 형식의 브라우저 호환 데이터를 개발하고 있습니다.

브라우저 호환성 데이터는 GitHub에 있으며 잘못된 정보가 있거나 여전히 이전 테이블을 사용하는 페이지를 발견하면 풀 요청을 제출할 수 있습니다. 저장소에는 기여 정보가 포함되어 있지만 시작하는 가장 간단한 방법은 기존 예제를 편집하는 것입니다. 최근에 CSS shape-outside 속성에 대한 정보를 업데이트했습니다. 속성에 이미 새 형식의 일부 데이터가 있었지만 불완전하고 올바르지 않았습니다.

이 데이터를 편집하기 위해 먼저 Browser Compat Data를 포크하여 나만의 포크를 만들었습니다. 그런 다음 이를 내 컴퓨터에 복제하고 변경 사항을 적용할 새 분기를 만들었습니다.

새 분기가 생겼을 때 shape-outside 용 JSON 파일을 찾았고 편집할 수 있었습니다. 나는 이미 속성에 대한 브라우저 지원에 대해 좋은 생각을 가지고 있었습니다. 또한 확실하지 않을 때 지원을 확인하기 위해 테스트하기 위해 shape-outside MDN 페이지의 라이브 예제를 사용했습니다. 따라서 편집 작업은 파일을 통해 작업하고 속성 지원을 위해 나열된 버전 번호를 확인하고 잘못된 것을 업데이트하는 경우였습니다.

파일이 JSON 형식이므로 모든 텍스트 편집기에서 편집하기가 매우 간단합니다. .editorconfig 파일은 이러한 문서에 대한 간단한 형식 지정 규칙을 설명합니다. 이 체크리스트에는 몇 가지 유용한 팁도 있습니다.

편집을 마친 후에는 변경 사항을 커밋하고 분기를 포크로 푸시한 다음 Browser Compat Data 리포지토리에 pull 요청을 할 수 있습니다. 실제 예와 마찬가지로 검토자가 사용자가 변경해야 할 사항이 있을 수 있습니다. Shapes 데이터에 대한 PR에서 데이터에 플래그를 지정하고 링크를 일부 변경해야 하는 방법에 몇 가지 오류가 있었습니다. 이것들은 만들기 쉬웠고 내 PR이 병합되었습니다.

시작하다

많은 경우에 추가할 항목을 선택하고 작업을 시작하여 간단히 시작할 수 있습니다. 질문이 있거나 이와 관련하여 도움이 필요한 경우 MDN Discourse 포럼에 게시할 수 있습니다. MDN은 제가 정보를 찾아보는 곳이고, 새로운 개발자와 숙련된 개발자를 모두 보내는 곳이며, 우리 모두가 더 나은 것을 만들기 위해 노력할 수 있다는 것이 장점입니다.

이전에 프로젝트에 대해 Pull Request를 한 적이 없다면 첫 번째 PR을 하기에 매우 친숙한 곳이며 제가 보여드린 것처럼 코드를 작성할 필요가 전혀 없는 기여할 수 있는 방법이 있습니다. 모든 문서 프로젝트에서 매우 가치 있는 기술은 작성, 편집 및 번역하는 기술입니다. 이러한 기술은 기술 문서를 더 쉽게 읽고 전 세계의 더 많은 사람들이 액세스할 수 있도록 하는 데 도움이 될 수 있기 때문입니다.