문서 폴더 구조

문서는 최상위 수준 관객 폴더 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 제품 및 기능을 참조할 때는 해당 문서에 링크해야 합니다. 최소한 처음 언급할 때는 링크를 포함해야 합니다.
  • 제 3자 제품이나 기술을 참조할 때는 외부 사이트, 문서 및 리소스로 링크해야 합니다.