이건 MDN에 있나요?

무엇인가를 문서로 남겨두겠다는 생각을 하기 시작했다면, 그 문서를 어디에 둘지도 고민해보았을 겁니다. 문서가 위치할 수 있는 몇 가지 장소가 있고, MDN이 웹에서 가장 큰 문서 저장소 중 하나이지만 유일한 옵션은 아닙니다. 또한 소스 코드에 문서를 보관해둘 수도 있고, Mozilla 위키나 git 저장소의 README 파일에 저장해 두어도 좋습니다. 이 글에서는 어느 방법이 여러분들의 문서와 어울릴지를 판단하는데 도움이 되기 위해서 쓰였습니다.

MDN에는 뭐가 있죠?

우리는 MDN에 정말 다양한 주제를 다룹니다. 하지만 완전히 MDN에 있어서는 안될 몇 가지도 있습니다. 이 섹션은 여러분의 문서가 MDN에 있어도 괜찮은지 판단할 수 있도록 도와주겠습니다.

MDN에서 다루는 것

우리는 MDN에서 정말 많은 내용을 다루고 있습니다. 일반적으로 완전히 제작되었거나 배포 중인 Mozilla 제품이나, 웹에 공개된 열린 기술이라면, MDN에 문서로 남겨둡니다.

우리들이 다루고 있는 내용 몇가지를 맛보기로 보여드리겠습니다. 전체 리스트는 아니지만 몇가지 아이디어는 줄 수 있을 겁니다.

열린 웹 기술
- HTML
- CSS
- JavaScript
- Web에 공개된 API
- 그 외 기타
Firefox OS
- 오픈 웹 애플리케이션
- Firefox OS 빌드하고 설치하기
- Firefox OS 프로젝트에 기여하기
- Gaia 설정 변경하기
- 그 외 기타
Mozilla 플랫폼
- Gecko
- Firefox를 빌드하고 설정하기
- XUL
- XPCOM
- 그 외 기타

참고하세요: 우리는 Mozilla 기술이 아니더라도 Web에 공개되어 있는 한 다룰 수 있다는 점이 중요합니다. 가령, 우리는 Webkit 전용 CSS 프로퍼티를 설명해놓은 문서도 있습니다.

우리가 다루지 않는 것

MDN에 문서로 남겨져서는 안되는 명백한 것인지 아닌지에 대해 스스로 질문해볼 수 있습니다.

아직 계획중인 문서인가?
아직 존재하지 않는 기술을 설명해놓은 설계 문서인가?
프로젝트를 제안하는 문서인가?
단순히 기술 스펙만 나열했는가?
Mozilla 브라우저가 아닌 특정 브라우저에만 사용되는 웹에 노출되지 않은 기술인가?

저 질문 중 하나라도 "예"라고 답변할 수 있다면, MDN에 있어서는 안될 문서입니다. 저 질문 모두에 "아니요"라고 대답할 수 있다면, MDN에 문서로 보관할지 진지하게 고민할 때가 되었다는 겁니다!

MDN에 문서로 남겨두면 좋은 점

MDN에 문서로 남겨두면 좋은 점이 굉장히 많답니다.

글을 쓰는 사람들이 굉장히 많습니다

MDN 공동체는 굉장히 큽니다. 정말 큽니다. 큰 것들을 작게 보이게 만들 정도로 큽니다. 농담이 아니라, 우리는 굉장히 많은 사람들과 MDN에 있는 자료를 만들어내며 관리하고 있습니다. 전세계 모든 땅(인정할게요. 남극까지는 잘 모르겠어요.)의 작가, 편집자들과 함께하고 있기 때문에, 글을 쓰려는 사람들은 무조건 득 보는 거에요.

우리에게는 우리의 컨텐츠를 최대한 좋게 만들어 보겠다는 사명을 갖고 있는 유급 편집 스탭이 있습니다.
우리는 충분한 양의 컨텐츠를 기여하고 여러분들을 도와줄 수 있는 핵심 커뮤니티와 함께하고 있습니다.
사실은 다른 사람들에게 여러분의 글의 대부분 혹은 전부를 쓰게 할 수 있는 절호의 찬스입니다!
넓디넓은 MDN 커뮤니티에게서 많은 것들을 얻어갈 수 있습니다. 오타를 잡아주는 것부터 시작해서 편집에 관한 논평까지, 여러분들의 소원을 들어줄 수 있습니다.
#mdn 채널을 통해 글쓰기 커뮤니티와 이야기를 하거나 조언을 들을 수 있고, 여러분들의 문서 제작이나 유지보수에 도움을 청할 수도 있습니다
전세계에 분포한 기여자들과 함께하고 있기 때문에, 언제나 누군가 주변에서 문제를 발견하고 해결해 줄 겁니다.

Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.

유지보수

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:

스팸 제거: 스팸이 발생하면 우리들이 처리합니다.
편집: 여러분 생각보다 필력이 달려도 걱정하실 것 없습니다. 여러분이 쓴 글을 다른 사람들이 읽을 수 있도록 해주겠습니다.
스타일의 일관성: 여러분이 작성한 문서 하나에서만 지켜지는 일관성이 아니라, 다른 문서와 함께 있을 때에도 일관적인 스타일을 가지고 있을지 봐주겠습니다.
컨텐츠 관리: 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.

다른 곳에 문서로 남겨두는 경우

MDN 말고 다른 곳에다가 여러분이 만든 작업물을 문서로 남겨둘 이유도 없는 건 아닙니다. 그런 이유에 대해서 몇가지 살펴보도록 하고, 각각 장단점을 찾아보도록 할게요.

계획이나 진행 상황

간단합니다. 계획, 진행 상황, 요청에 대한 문서는 MDN에 남기면 안됩니다.

Github에 올라온 프로젝트

Mozilla의 몇몇 프로젝트는 Github에 올라와 있습니다. 또, Github에는 문서를 보관하기 위해 자기네들만의 위키 비스무리한 시스템을 가지고 있어요. 몇몇 팀은 거기에다가 문서를 남겨두기를 더 좋아합니다. 여러분만의 문서를 만들어갈 생각이라면 아무래도 그쪽이 더 편하고 좋겠죠. 하지만 몇가지 사실을 기억하세요.

MDN 문서 팀이 여러분들을 도와드릴 수 없을지도 모릅니다. 우리는 일반적으로(때로 예외가 있기는 합니다만) MDN 바깥의 문서화에는 참여하지 않습니다.
여러분들의 문서다 다른 관련된 내용과 상호 링크하기가 힘들거나 불가능합니다.
다른 문서와 일관된 스타일을 가지지 못할 수도 있습니다.
다른 문서 사이에 없기 때문에 발견될 가능성이 줄어듭니다.
Github에 저장된 문서는 MDN에 있는 문서에 비해 별로 매력적으로 보이지도 않으면서 가독성도 영 좋지는 않습니다.

물론 이런 점들이 여러분들에게 별로 문제가 되지 않거나 문제가 되더라도 딱히 불편한 점이 없을 수도 있습니다. 몇몇 팀은 문서로 남기겠다는 필요성이 별로 없어서 코드 안에서만 작업하고 문서를 남겨두기도 합니다.

소스 안에 문서를 남겨두고 싶은 경우

몇몇 팀은 소스 저장소에다가 자신들의 문서를 저장하는 걸 더 선호하기도 합니다. 내부 프로젝트나 라이브러리 프로젝트에서는 꽤나 흔한 일이긴 한데요. 코드를 쓰듯이 자신들의 기술을 문서로 남길 수 있다는 점에서 이점이 있기는 합니다. 하지만 그만큼 단점도 있지요.

MDN 문서 팀이 여러분들을 도와드릴 수 없습니다. 코드가 Mozilla의 소스 저장소에 있더라도, 리뷰나 체크인 시스템은 문서 팀이 참여하기에는 그닥 효율적이지 못합니다.
관련 있는 다른 문서와 상호 링크할 수 있는 간편한 도구를 찾기가 힘듭니다. 상호 링크를 하면 읽는 이들에게 맥락과 중요한 정보를 더 잘 전달할 수 있을텐데 말이죠.
다른 문서 사이에 없기 때문에 발견될 가능성이 줄어듭니다.
(JavaDoc 같은) 변환 도구를 사용하여 웹에서 읽을 수 있는 문서를 만들더라도, MDN에서 할 수 있는것보다 예쁘거나 매력적이지도 않을 겁니다.

여전히 몇몇 프로젝트에서 이런 방법을 사용할 수 없는 건 아닙니다. (오히려 좋은 방법일 수도 있습니다.) 작은 프로젝트나 별로 관심을 얻을 생각을 하지 않는 프로젝트에는 특히 그렇죠.

나중에는

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.