문서에 대한 폴더 구조

문서는 최상위 관객 폴더로 구분됩니다 user, administration, 및 development (기여) 폴더.

그 외에도, 우리는 주로 GitLab 사용자 인터페이스 또는 API의 구조를 따릅니다.

우리의 목표는 docs.gitlab.com/user/project/merge_requests/와 같은 의미 있는 URL을 가진 명확한 계층 구조를 갖는 것입니다. 이 패턴을 통해 사용자가 프로젝트 기능에 대한 문서, 특히 병합 요청에 대한 사용자 관련 문서를 탐색하고 있다는 것을 즉시 알 수 있습니다. 우리 사이트의 경로는 리포지토리의 경로와 일치하므로, 명확한 구조를 통해 문서를 업데이트하기도 더 쉽습니다.

특정 제품 영역에 대한 파일을 관련 폴더에 넣습니다:

디렉토리 내용
doc/user/ 사용자를 위한 문서입니다. GitLab 사용자 인터페이스에서 수행할 수 있는 모든 것이 여기에 들어갑니다, /admin 인터페이스의 사용도 포함됩니다.
doc/administration/ GitLab이 설치된 서버에 접근할 수 있는 사용자가 필요로 하는 문서입니다. GitLab 사용자 인터페이스의 관리자 설정은 doc/administration/에 있습니다.
doc/api/ API에 대한 문서입니다.
doc/development/ GitLab 개발과 관련된 문서입니다, 코드 또는 문서 기여 여부에 관계없이. 관련 프로세스와 스타일 가이드는 여기에 있어야 합니다.
doc/legal/ GitLab에 기여하는 것에 대한 법적 문서입니다.
doc/install/ GitLab 설치에 대한 지침입니다.
doc/update/ GitLab 업데이트에 대한 지침입니다.
doc/tutorials/ GitLab 사용 방법에 대한 튜토리얼입니다.

다음은 레거시 또는 더 이상 사용되지 않는 폴더입니다. 이 폴더에 새로운 콘텐츠를 추가하지 마세요:

  • /gitlab-basics/
  • /topics/
  • /university/

디렉토리 및 파일 작업하기

디렉토리 및 파일 작업 시:

  1. 새 디렉토리를 만들 때는 항상 index.md 파일로 시작하세요. 다른 파일 이름을 사용하지 말고 README.md 파일을 생성하지 마세요.

  2. 파일 이름, 디렉토리 이름, 브랜치 이름 및 경로를 생성하는 모든 것에 특별한 문자와 공백 또는 대문자를 사용하지 마세요.

  3. 파일이나 디렉토리를 생성하거나 이름을 바꿀 때, 이름에 여러 단어가 포함되어 있으면 공백이나 하이픈 대신 밑줄(_)을 사용하세요. 예를 들어, 올바른 이름은 import_project/import_from_github.md입니다. 이 규칙은 이미지 파일과 Markdown 파일 모두에 적용됩니다.

  4. 제품 리포지토리에 비디오 파일을 업로드하지 마세요. 대신 링크하거나 비디오를 삽입하세요.

  5. doc/user/ 디렉토리에는:
    • doc/user/project/는 모든 프로젝트 관련 문서를 포함해야 합니다.
    • doc/user/group/는 모든 그룹 관련 문서를 포함해야 합니다.
    • doc/user/profile/는 모든 프로필 관련 문서를 포함해야 합니다. /profile 아래에서 탐색할 수 있는 모든 페이지는 account.md, applications.md 또는 emails.md와 같이 각자의 문서를 가져야 합니다.
  6. doc/administration/ 디렉토리에는: 관리자와 관련된 모든 문서가 포함되어야 하며, UI 및 백엔드 서버 모두에서 수행되는 관리자 작업이 포함됩니다.

문서나 콘텐츠 추가를 어디에 두어야 할지 잘 모를 경우, 이것이 저자 작업이나 기여를 막지 않도록 하세요. 최선의 판단을 사용한 후, MR의 리뷰어에게 결정을 확인해 줄 것을 요청하세요. 또한, 과정의 어느 단계에서나 기술 작가에게 문의할 수 있습니다. 기술 문서 팀은 모든 문서 변경 사항을 검토하며, 더 나은 장소가 있다면 콘텐츠를 이동할 수 있습니다.

중복 피하기

같은 정보를 여러 곳에 포함하지 마세요.

단일 신뢰할 수 있는 출처에 링크하세요.

예를 들어, 주요 리포지토리 외에 코드가 있는 리포지토리와 같은 리포지토리에 문서가 있는 경우, 해당 리포지토리에 문서를 보관할 수 있습니다.

그런 다음, 다음 중 하나를 선택할 수 있습니다:

문서 간 참조

  • 각 폴더에 주제를 소개하고 자식 페이지에 연결하는 index.md 페이지를 제공합니다. 이는 다음 수준의 하위 경로의 인덱스 페이지를 포함합니다.

  • 검색 가능성을 보장하기 위해, 각 새 문서나 이름이 변경된 문서는 상위 수준의 인덱스 페이지 및 기타 관련 페이지에서 링크되어야 합니다.

  • 다른 GitLab 제품 및 기능을 언급할 때는 처음 언급할 때 해당 문서에 링크해야 합니다.

  • 타사 제품이나 기술을 언급할 때는 해당 외부 사이트, 문서 및 리소스에 링크를 추가합니다.