문서 폴더 구조

문서는 최상위 수준의 청중 폴더인 user, administration, 그리고 development (contributing) 폴더로 구분됩니다.

이를 넘어서, 주로 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 페이지에 대한 소개 및 링크가 있는 index.md 페이지를 제공합니다.
  • 발견성을 보장하기 위해, 새 문서 또는 이름이 변경된 문서는 상위 수준 index 페이지 및 관련 페이지에서 링크가 걸립니다.
  • 다른 GitLab 제품 및 기능을 참조할 때, 최소한 첫 번째 언급에는 해당하는 문서에 링크를 걸어줍니다.
  • 제3자 제품이나 기술을 참조할 때, 외부 사이트, 문서 및 리소스에 대한 링크를 추가합니다.