문서 구조 폴더
문서는 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/
디렉터리 및 파일 작업
디렉토리 및 파일을 다룰 때:
- 새 디렉토리를 만들 때 항상
index.md
파일로 시작하십시오. 다른 파일 이름을 사용하지 말고README.md
파일을 만들지 마십시오. - 파일 이름, 디렉터리 이름, 브랜치 이름 및 경로를 생성하는 모든 것에 특수 문자와 공백, 대문자를 사용하지 마십시오.
- 파일 또는 디렉토리를 생성하거나 이름을 바꿀 때 두 단어 이상으로 이루어진 경우 하이픈(
-
) 대신 언더스코어(_
)를 사용하십시오. 예를 들어,import_project/import_from_github.md
와 같이 적절하게 명명해야 합니다. 이는 이미지 파일과 마크다운 파일 둘 다 적용됩니다. - 제품 저장소에 비디오 파일을 업로드하지 마십시오. 링크 또는 비디오를 포함하십시오.
-
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 제품 및 기능을 참조할 때는 첫 번째 언급에서 적어도 해당 문서에 링크해야 합니다.
- 타사 제품이나 기술을 참조할 때는 외부 사이트, 문서 및 자료에 링크해야 합니다.