문서 폴더 구조
문서는 최상위 수준 관객 폴더 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/
디렉터리 및 파일 사용
디렉터리 및 파일을 다룰 때:
- 새 디렉터리를 생성할 때 항상
index.md
파일로 시작합니다. 다른 파일 이름을 사용하지 마시고README.md
파일을 만들지 마십시오. - 파일 이름, 디렉터리 이름, 브랜치 이름 및 경로를 생성하는 모든 것에서 특수 문자, 공백, 대문자를 사용하지 마십시오.
- 파일 또는 디렉터리를 생성하거나 이름을 변경할 때 이름에 두 개 이상의 단어가 포함되어 있다면, 공백이 아닌 밑줄(
_
)을 사용하십시오. 예:import_project/import_from_github.md
. 이는 이미지 파일 및 Markdown 파일에도 적용됩니다. - 제품 리포지터리에 비디오 파일을 업로드하지 마십시오. 대신 비디오를 링크하거나 임베드하십시오.
-
doc/user/
디렉터리에서:-
doc/user/project/
는 모든 프로젝트 관련 문서를 포함해야 합니다. -
doc/user/group/
는 모든 그룹 관련 문서를 포함해야 합니다. -
doc/user/profile/
은 모든 프로필 관련 문서를 포함해야 합니다./profile
아래로 이동하는 페이지마다account.md
,applications.md
, 또는emails.md
와 같은 문서가 있어야 합니다.
-
-
doc/administration/
디렉터리에서: 모든 관리자 관련 문서를 포함해야 합니다. UI 및 백엔드 서버에서 수행하는 관리 작업이 포함됩니다.
문서나 콘텐츠를 배치할 위치를 확신하지 못해도 저자로서 기여하지 말아야 하는 일은 없습니다. 최선의 판단을 행한 후 MR 리뷰어에게 확인을 요청하십시오. 프로세스 중에 기술 작가에게도 질문할 수 있습니다. 기술 작성 팀은 모든 문서 변경을 리뷰하고 필요하다면 콘텐츠를 이동할 수 있습니다.
중복 피하기
동일한 정보를 여러 곳에 포함하지 마십시오. 대신 단일 정보 원천에 링크해야 합니다.
예를 들어, 주된 리포지터리 이외의 리포지터리에 코드 및 문서가 있는 경우, 해당 리포지터리에 문서를 유지할 수 있습니다.
그런 다음 다음 중 하나를 할 수 있습니다:
- https://docs.gitlab.com에 발행합니다.
- 글로벌 내비게이션에 항목을 추가하여 https://docs.gitlab.com에 연결합니다. 예시 보기.
문서 간 참조
- 각 폴더에 주제를 소개하고 하위 페이지 및 다음 수준 하위 경로의 인덱스 페이지에 대한 링크를 포함하는
index.md
페이지를 제공하십시오. - 발견 가능성을 보장하기 위해 각 새로운 또는 이름이 변경된 문서가 상위 수준 인덱스 페이지 및 다른 관련 페이지에서 링크되도록 하십시오.
- 기타 GitLab 제품 및 기능을 참조할 때는 해당 문서에 링크해야 합니다. 최소한 처음 언급할 때는 링크를 포함해야 합니다.
- 제 3자 제품이나 기술을 참조할 때는 외부 사이트, 문서 및 리소스로 링크해야 합니다.