문서 구조 폴더

문서는 user, administrations, 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와 같이 적절하게 명명해야 합니다. 이는 이미지 파일과 마크다운 파일 둘 다 적용됩니다.
  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 제품 및 기능을 참조할 때는 첫 번째 언급에서 적어도 해당 문서에 링크해야 합니다.
  • 타사 제품이나 기술을 참조할 때는 외부 사이트, 문서 및 자료에 링크해야 합니다.