문서는 최상위 독자 기준 폴더인 user, administration, development(기여) 폴더로 나뉩니다.

그 아래로는 기본적으로 GitLab 사용자 인터페이스나 API의 구조를 따릅니다.

목표는 docs.gitlab.com/user/project/merge_requests/처럼 의미가 분명한 URL을 갖춘 명확한 계층 구조를 만드는 것입니다. 이런 패턴을 쓰면 프로젝트 기능, 그중에서도 머지 리퀘스트에 관한 사용자용 문서로 이동하고 있다는 사실을 바로 알 수 있습니다. 사이트 경로가 리포지터리 경로와 일치하므로, 이 명확한 구조는 문서를 업데이트하기도 쉽게 만들어 줍니다.

특정 제품 영역에 해당하는 파일은 관련 폴더에 넣습니다.

다음은 레거시이거나 더 이상 사용하지 않는 폴더입니다. 이 폴더에는 새 콘텐츠를 추가하지 않습니다.

• /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 리뷰어에게 그 결정이 적절한지 확인받으면 됩니다. 과정 중 어느 단계에서든 테크니컬 라이터에게 문의할 수도 있습니다. 테크니컬 라이팅 팀은 어떤 경우에도 모든 문서 변경을 검토하며, 더 적합한 위치가 있다면 콘텐츠를 옮길 수 있습니다.

중복 최소화#

가능하다면 같은 정보를 여러 곳에 넣지 않습니다. 대신 단일 진실 공급원(Single Source Of Truth, SSOT) 한 곳으로 링크합니다.

예를 들어 주요 리포지터리가 아닌 다른 리포지터리에 코드가 있고 문서도 같은 리포지터리에 있다면, 그 리포지터리에 문서를 그대로 두어도 됩니다.

그런 다음 다음 중 하나를 선택합니다.

• https://docs.gitlab.com에 게시합니다.
• 전역 내비게이션에 항목을 추가해 https://docs.gitlab.com에서 링크합니다.

문서 간 참조#

• 각 폴더에는 주제를 소개하고, 다음 단계 하위 경로의 인덱스 페이지를 포함한 하위 페이지를 소개하고 링크하는 _index.md 페이지를 둡니다.
• 발견 가능성을 확보하려면 새로 만들거나 이름을 바꾼 문서를 상위 인덱스 페이지와 관련 페이지에서 링크합니다.
• 다른 GitLab 제품이나 기능을 언급할 때는 적어도 첫 언급에서 해당 문서로 링크합니다.
• 서드파티 제품이나 기술을 언급할 때는 해당 외부 사이트와 문서, 자료로 링크합니다.