Technical Writing 팀은 다음 사항에서 기여자, 개발자, 제품 관리자와 협업하기 위해 워크플로를 사용합니다.

• 제품 문서 변경
• UI 텍스트
• 릴리스 포스트

제품 변경에 대한 문서#

GitLab 제품 문서를 작성하고 유지 관리하는 절차는 해당 문서가 다음 중 어느 쪽인지에 따라 달라집니다.

• 새 기능 또는 기능 개선: 특정 마일스톤에 맞춰 제공되며 특정 코드 변경과 연관됩니다. 이 문서가 가장 높은 우선순위를 가집니다.
• 특정 마일스톤 외부의 변경: 일반적으로 특정 코드 변경과 연관되지 않고, 우선순위가 낮으며 모든 GitLab 기여자에게 열려 있습니다.

마일스톤에 문서가 필요한 경우는 다음과 같습니다.

• 사용자 또는 관리자 경험에 영향을 주는 새 기능이나 개선된 기능이 출시되는 경우.
• 사용자 인터페이스 또는 API에 변경이 있는 경우.
• 프로세스, 워크플로 또는 이전에 문서화된 기능이 변경되는 경우.
• 기능이 사용 중단되거나 제거되는 경우.

백엔드 기능이 추가되거나 변경되는 경우에는 일반적으로 문서가 필요하지 않습니다.

개발자 책임#

개발자는 기능 또는 기능 개선에 대한 문서의 주 작성자입니다. 개발자는 다음 사항을 책임집니다.

• 기능에 필요한 초기 콘텐츠를 개발합니다.
• 어떤 문서를 언제 제공해야 하는지 파악하기 위해 제품 관리자와 협의합니다.
• 같은 그룹의 다른 개발자에게 기술 검토를 요청합니다.
• 새 기능 또는 기능 개선을 제공하는 DevOps stage 그룹에 배정된 Technical Writer에게 문서 검토를 요청합니다.

가능하면 코드가 포함된 머지 리퀘스트에 문서를 함께 포함해야 합니다. 자세한 내용은 가이드라인을 참고합니다.

이 MR의 작성자, 즉 프론트엔드 또는 백엔드 개발자가 문서를 작성해야 합니다.

작성#

문서는 제품의 필수 구성 요소이므로, ~"type::feature" 이슈에 ~documentation 레이블이 함께 붙어 있으면 새로 작성하거나 업데이트한 문서를 기능 코드와 함께 출시해야 합니다.

Technical Writer는 이슈 단위로 요청하고 계획한 대로 기꺼이 지원합니다.

문서가 필요한 기능 이슈에서는 제품 관리자와 Technical Writer가 달리 합의하지 않은 한 다음 절차를 따릅니다.

• 새로 작성하거나 편집한 문서를 다음 중 한 곳에 포함합니다.

  • 코드를 도입하는 머지 리퀘스트.
  • 같은 시기에 올리는 별도의 머지 리퀘스트.

• 제품 관리자가 이슈에서 작성한 문서 요구 사항을 사용하고, 필요에 따라 추가 문서 계획이나 아이디어를 논의합니다.

  새로 작성하거나 변경한 문서에 폭넓은 협업이나 논의가 필요하면, 계획 과정에 연결된 별도 이슈를 사용할 수 있습니다.

• 문서 가이드라인과 거기에 연결된 다음 자료를 활용합니다.

  • 문서 폴더 구조.
  • 문서 스타일 가이드.
  • Markdown 가이드.

• 다음과 같은 경우에는 이슈나 머지 리퀘스트 또는 #docs Slack 채널에서 해당 DevOps stage 담당 Technical Writer에게 문의합니다.

  • 문서를 넣을 올바른 위치를 고르는 데 도움이 필요한 경우.
  • 문서 아이디어나 개요를 논의하려는 경우.
  • 그 밖의 도움을 요청하려는 경우.

• 별도의 머지 리퀘스트에서 문서를 작업하는 경우에는 코드 머지와 최대한 가까운 시점에 문서가 머지되도록 합니다.

• 기능에 기능 플래그가 있으면 기능 플래그가 적용된 이슈의 문서화 정책을 따릅니다.

AI 생성 문서#

AI가 생성한 모든 문서는 Technical Writer의 검토를 받아야 합니다. 문서를 검토에 제출하기 전에 문서 파일에 Vale 테스트를 실행해 스타일 문제를 찾아 수정합니다.

생성형 AI 도구는 해당 분야의 전문성을 대체하지 않습니다. 작성자는 자신이 만든 콘텐츠의 기술적 정확성을 보장할 책임이 있습니다. 산출물 품질에 대한 자세한 내용은 생성형 AI 도구를 사용할 때의 커뮤니케이션을 참고합니다.

검토#

머지하기 전에 개발자가 커밋한 문서 변경은 다음 주체의 검토를 받아야 합니다.

• 머지 리퀘스트의 코드 리뷰어. 이를 기술 검토라고 합니다.
• 선택 사항으로, 다른 개발자나 제품 관리자처럼 해당 작업에 관여한 그 밖의 인원.
• DevOps stage 그룹의 Technical Writer. 다만 예외적인 상황에서는 머지 후 검토를 요청할 수 있습니다.
• 프로젝트의 Maintainer.

머지 후 검토#

GitLab에서는 문서를 코드처럼 다룹니다. 코드와 마찬가지로 품질을 보장하기 위해 문서도 검토를 받아야 합니다. 문서는 GitLab 완료 정의의 일부이며, 마일스톤 릴리스 전에 완료해야 합니다.

문서는 때때로 Technical Writer 검토 없이 기능과 함께 머지됩니다. 머지 전에 Technical Writer 검토가 배정되지 않았다면, 개발자나 Maintainer는 머지 직후에 검토를 예약해야 합니다. 이를 위해 Doc Review 설명 템플릿으로 이슈를 생성하고 문서 변경을 도입한 머지된 머지 리퀘스트 링크를 추가합니다.

머지 후 Technical Writer 검토가 이루어질 수 있는 상황은 다음과 같습니다.

• 마일스톤 릴리스까지 남은 시간이 얼마 없는 경우. 3일 미만이 남았다면 머지 후 검토를 요청하고, Slack에서 작성자를 호출해 검토가 최대한 빨리 완료되도록 합니다.
• 변경 규모가 작고, 해당 기능의 초기 사용자(예: GitLab.com 사용자)가 작성된 문서를 그대로 쉽게 사용할 수 있다고 높은 수준으로 확신하는 경우.

Technical Writer는 Technical Writer 검토 없이 문서를 머지할 수 있는지 판단하는 데 도움을 줄 수도 있지만, 머지 후 검토는 최대한 빨리 이루어져야 합니다.

제품 관리자 책임#

제품 관리자는 기능 또는 기능 개선에 대한 문서 요구 사항을 책임집니다. 또한 다음을 수행할 수 있습니다.

• Technical Writer와 논의하고 협업합니다.
• 직접 문서를 검토합니다.

새 문서나 업데이트된 문서가 필요한 이슈에서 제품 관리자는 다음을 수행해야 합니다.

• ~documentation 레이블을 추가합니다.
• 문서 요구 사항을 확인하거나 추가합니다.
• 이슈에 다음 내용이 포함되도록 합니다.
  • 새로 추가되거나 업데이트된 기능 이름.
  • 해당하는 경우 개요, 설명, 사용 사례 (문서 폴더 구조에서 요구하는 대로).

누구나 이슈에 문서 요구 사항 초안을 작성할 수 있습니다. 다만 제품 관리자는 다음을 수행합니다.

• 이슈에 릴리스 마일스톤이 배정되면 Documentation 세부 정보를 검토하고 업데이트합니다.
• 킥오프 시점까지 문서 세부 정보를 확정합니다.

Technical Writer 책임#

Technical Writer는 다음 사항을 책임집니다.

• 다음 마일스톤의 이슈 논의에 참여하고 MR을 검토합니다.
• 요청받은 경우 이슈의 문서 요구 사항을 검토합니다.
• 질문에 답하고, 작성 및 편집 과정 전반에서 도움과 조언을 제공합니다.
• 머지 전이든 머지 후든 중요한 신규·업데이트 문서 콘텐츠를 모두 검토합니다.
• 개발자와 제품 관리자가 기능 문서를 제공하도록 지원합니다.
• 이슈와 MR에 적절한 레이블이 붙고, 문서 콘텐츠에 올바른 메타데이터가 있도록 합니다.

계획#

Technical Writer는 다음을 수행합니다.

• 작성할 콘텐츠의 범위를 파악하기 위해 다음 마일스톤에 포함된 담당 그룹의 ~"type::feature" 이슈를 검토합니다.
• 그 목록에서 ~documentation 레이블이 있어야 하는데 없는 이슈에 해당 레이블을 권고하거나, 문서가 실제로 필요한지 판단하기 위해 PM에게 문의합니다.
• 그 목록의 ~direction 이슈에 대해서는 이슈 전체를 읽고 Documentation requirements 섹션을 검토합니다. Documentation requirements를 다듬거나 확장하기 위해 해당 이슈에서 협업하는 PM 및 다른 인원과 함께 권고 사항이나 질문을 처리합니다.
• Technical Writing 마일스톤 계획을 업데이트합니다(이슈 템플릿에서 생성한 예시).
  • 다음 마일스톤에 계획된 문서 및 UI 텍스트 작업을 보여 주는 보드나 필터 링크를 추가합니다.
  • 그룹 PM 또는 EM이 계획된 작업을 알고 있는지 확인합니다.

협업#

기본적으로 개발자가 문서 변경을 단독으로 진행하지만, 개발자, 제품 관리자, Technical Writer 중 누구든 특정 이슈에 대해 더 폭넓은 협업을 제안할 수 있습니다.

또한 Technical Writer에게는 언제든 질문할 수 있습니다.

검토#

Technical Writer는 변경이 머지되기 전이든 후이든 모든 문서 변경에 대해 차단하지 않는 검토를 제공합니다. 변경의 릴리스를 막거나 지연시킬 수 있는 문제로 확인된 사항은 연결된 후속 MR에서 처리합니다.

문서 요구 사항#

기능 문서 요구 사항은 해당 기능을 계획하는 이슈의 설명에서 Documentation 섹션에 포함해야 합니다. Feature Proposal 템플릿을 사용해 생성한 이슈에는 기본적으로 이 섹션이 있습니다.

누구나 이 세부 정보를 추가할 수 있지만, 이슈를 특정 릴리스 마일스톤에 배정하는 제품 관리자가 해당 마일스톤 킥오프 시점까지 이 세부 정보가 존재하고 확정되도록 합니다.

개발자, Technical Writer, 그 밖의 인원은 요청에 따라 언제든 이 계획을 더 다듬는 데 도움을 줄 수 있습니다.

다음 세부 정보를 포함해야 합니다.

• 문서가 안내해 사용자가 이해하거나 수행할 수 있게 해야 하는 개념과 절차.
• 이를 위해 필요한 새 페이지가 있는지, 업데이트가 필요한 페이지나 하위 섹션이 무엇인지. 사용자·관리자·API 문서의 변경과 추가를 고려합니다.
• 가이드나 지침 모음이 단일 사용 사례를 다루어야 하는지, 아니면 일정 범위의 사용 사례를 유연하게 다루어야 하는지.
• 이전에 권장한 워크플로를 업데이트해야 하는지, 관련된 여러 위치에서 새 기능을 연결해야 하는지. 문서가 영향을 받는 모든 경우를 고려합니다.
• 관련 검색에서 문서가 발견되도록 포함해야 하는 핵심 용어나 작업 설명이 있는지.
• 해당하는 경우 페이지 제목이나 하위 섹션 제목 제안을 포함합니다.
• 해당하는 경우 상호 연결해야 하는 문서를 나열합니다.

코드와 함께 문서 포함#

현재 Technical Writing 팀은 문서를 관련 코드와 같은 머지 리퀘스트에 포함하도록 강력히 권장하지만, 엄격한 의무 사항은 아닙니다. 기능 MR과 별도의 MR에서 문서를 추가하는 일도 여전히 흔합니다.

엔지니어링 팀은 문서를 코드 MR에 반드시 포함하는 워크플로를 자체 완료 정의의 일부로 채택할 수 있습니다. 팀이 이 워크플로를 채택하면 해당 팀의 엔지니어는 항상 문서를 기능 코드와 같은 MR에 포함해야 합니다.

별도의 문서 MR의 단점#

문서를 별도 MR로 분리하는 워크플로에는 여러 단점이 있습니다.

문서가 기능보다 먼저 머지되는 경우:

• GitLab.com 사용자가 기능이 릴리스되기 전에 사용을 시도해 지원 티켓이 늘어날 수 있습니다.
• 기능이 지연되면 문서를 제때 내리거나 되돌리지 못해, 해당 릴리스의 GitLab Self-Managed에 실수로 포함될 수 있습니다.

문서가 기능보다 나중에 머지되는 경우:

• 문서 MR이 마감을 놓치면 기능은 GitLab Self-Managed에 포함되지만 문서는 전혀 없을 수 있습니다.
• 문서가 존재하기 전에 기능이 GitLab.com 사용자 인터페이스에 나타날 수 있습니다. 이 기능에 놀란 사용자는 문서를 검색하지만 찾지 못하고, 그 결과 지원 티켓이 늘어날 수 있습니다.

MR이 두 개로 나뉘면 다음을 의미합니다.

• 한 기능의 머지를 서로 다른 두 사람이 맡게 되는데, 이는 비동기 업무 방식과 맞지 않습니다. Technical Writer가 자고 있는 동안 기능이 머지되어 두 머지 사이에 상당히 긴 지연이 생길 수 있습니다.
• 문서 MR이 기능 코드 MR을 담당하는 같은 Maintainer에게 배정되면, 그 사람은 MR 하나만 처리하는 대신 두 개를 검토하며 병행해야 합니다.

다음 이유로 문서 품질이 낮아질 수 있습니다.

• 문서를 별도 MR에 두면 문서를 보고 검증하는 사람이 훨씬 줄어들어 문제를 놓칠 가능성이 커집니다.
• 분리된 워크플로에서는 엔지니어가 기능 MR이 준비되거나 거의 준비된 뒤에야 문서 MR을 만들 수 있습니다. 그러면 Technical Writer가 좋은 검토를 하기 위해 기능을 파악할 시간이 거의 없습니다. 또한 원하는 속도보다 빠르게 검토하고 머지해야 한다는 압박이 커져, 서두르는 탓에 문제가 스며들게 됩니다.

항상 코드와 함께 문서를 포함하는 이점#

문서를 코드와 함께 포함하고 그것을 개발 과정 초기에 수행하면 다음과 같은 여러 이점이 있습니다.

• 릴리스와 관련된 시점 문제가 없습니다.
  • 기능이 다음 릴리스로 미뤄지면 문서도 함께 미뤄집니다.
  • 기능이 간신히 릴리스에 들어가면 문서도 함께 간신히 들어갑니다.
  • 기능이 GitLab.com에 먼저 들어가면 문서는 얼리 어답터를 위해 준비되어 있습니다.
• 기능 머지를 담당하는 사람이 한 명(코드 Maintainer)으로 한정됩니다.
• Technical Writer가 기능을 이해할 시간을 더 확보하고, Review App이나 GDK에서 문서 내용을 더 잘 검증할 수 있습니다. 또한 사용자 인터페이스 텍스트를 개선할 조언을 제공하거나 추가 사용 사례를 제시할 수 있습니다.
• 문서의 가시성이 높아집니다.
  • 머지 리퀘스트에 관여한 모든 사람이 문서를 검토할 수 있습니다. 여기에는 제품 관리자, 도메인 지식이 깊은 여러 엔지니어, 코드 리뷰어, Maintainer가 포함될 수 있습니다. 이들은 예시의 문제, 그리고 Technical Writer가 모를 수 있는 배경이나 개념의 문제를 더 잘 찾아낼 수 있습니다.
  • 문서의 가시성이 높아지면 다른 엔지니어의 문서도 개선되는 부수 효과가 있습니다. 서로의 MR을 검토하면서 각 엔지니어의 문서 작성 역량이 향상됩니다.
• 문서를 일찍 고민하면 엔지니어가 더 나은 예시를 만드는 데 도움이 됩니다. 사용자가 어떤 예시를 원할지 생각해야 하고, 자신이 작성하는 코드가 그 예시를 제대로 구현하는지 확인해야 하기 때문입니다.

워크플로로서 코드와 함께 문서 포함#

문서를 코드와 함께 포함하는 것을 의무 워크플로로 만들려면 팀의 현재 워크플로에 몇 가지 변경이 필요할 수 있습니다.

• 엔지니어는 Technical Writer뿐 아니라 코드 리뷰어와 Maintainer에게도 충분한 검토 시간을 주기 위해, 개발 과정 초기에 문서를 포함하도록 노력해야 합니다.
• 리뷰어와 Maintainer도 코드 검토 중에 문서를 검토해, 서술된 프로세스가 기능의 예상 사용 방식과 일치하고 예시가 정확한지 확인해야 합니다. 스타일이나 문법은 신경 쓰지 않아도 됩니다.
• Technical Writer를 호출만 하지 말고 MR의 리뷰어로 직접 배정해야 합니다. 배정은 언제든 할 수 있지만 코드 Maintainer 검토 전에는 해야 합니다. 문서 검토와 코드 검토가 동시에 진행되면서 작성자, 리뷰어, Technical Writer가 함께 문서를 논의하는 경우가 흔합니다.
• 문서가 준비되면 Technical Writer가 Approve를 선택하고, 이후에는 보통 해당 MR에 더 관여하지 않습니다. 코드 검토 중에 기능이 변경되어 문서가 업데이트되면, 업데이트를 검증하도록 Technical Writer에게 MR을 다시 배정해야 합니다.
• Maintainer는 Technical Writer가 아직 최종 승인을 하지 않았더라도 문서를 있는 그대로 둔 채 기능을 머지할 수 있습니다. 문서 검토는 차단 요소가 되어서는 안 됩니다. 그러므로 문서를 일찍 포함하고 Technical Writer에게 일찍 배정하는 것이 중요합니다. 최종 문서 승인 전에 기능이 머지되면 Maintainer는 머지 후 후속 이슈를 생성하고, 이를 엔지니어와 Technical Writer 양쪽에 배정해야 합니다.

코드 검토와 문서 검토의 병렬 워크플로는 다음과 같이 시각화할 수 있습니다.

graph TD
  A("Feature MR Created (Engineer)") --> |Assign| B("Code Review (reviewer)")
  B --> |"Approve / Reassign"| C("Code Review (maintainer)")
  C --> |Approve| F("Merge (maintainer)")
  A --> D("Docs Added (Engineer)")
  D --> |Assign| E("Docs Review (Tech Writer)")
  E --> |Approve| F

여러 머지 리퀘스트로 나뉜 복잡한 기능의 경우:

• 머지 리퀘스트가 향후 기능의 구성 요소를 구현하지만 그 구성 요소를 사용자가 아직 사용할 수 없다면, 문서를 포함하지 않아야 합니다.
• 활성화된 사용자 인터페이스 요소나 API 엔드포인트처럼, 머지 리퀘스트가 어떤 형태로든 기능을 사용자에게 노출한다면 그 MR에는 문서가 있어야 합니다. 이는 하나의 큰 기능을 구현해 가는 과정에서 문서 추가가 여러 번 일어날 수 있다는 뜻입니다. 예를 들어 API 문서와 기능 사용 문서를 각각 추가합니다.
• 어느 엔지니어가 자신의 MR에 기능 문서를 추가해야 하는지 불분명하면, 엔지니어링 매니저가 계획 단계에서 결정하고, 기능이 릴리스된 것으로 간주되기 전에 머지해야 하는 마지막 MR에 문서를 연결합니다. 이는 항상 그렇지는 않지만 대개 프론트엔드 MR입니다.

문서 숨기기 대신 삭제#

기능이 준비되기 전에 추가했거나 미완성인 문서, 또는 그와 비슷한 이유로 숨기려는 문서에 HTML 주석을 사용하지 않습니다. 문서를 숨기면 다음과 같은 여러 문제가 생깁니다.

• 예상치 못한 차단 요소로 기능이 무기한 지연될 수 있습니다.
• 숨겨진 문서는 개발 중 기능이 발전하면서 낡은 내용이 됩니다.
• 폐기된 기능은 고아 콘텐츠를 남겨, 발견될 때까지 리포지터리를 어지럽힙니다.

문서를 너무 이르게 추가해 제거해야 한다면 삭제합니다. 콘텐츠를 제거하는 머지 리퀘스트에는 원래 그 콘텐츠를 추가한 머지 리퀘스트 링크를 추가합니다. 나중에 필요해지면 Git 히스토리나 이전 MR을 사용해 콘텐츠를 복구하고 다시 추가할 수 있습니다.

문서가 너무 이르게 추가되는 일을 막으려면 개발 팀이 문서를 코드와 함께 포함하는 방안을 고려해야 합니다.

UI 텍스트#

계획 및 작성#

제품 디자이너는 UI 텍스트를 추가하거나 변경할 계획이라면 해당 stage 그룹의 Technical Writer와 상의해야 합니다.

Technical Writer는 아이디어, 계획, 실제 텍스트에 대해 1차 검토를 제공할 수 있습니다. 텍스트의 컨텍스트와 목적을 제공하면 Technical Writer에게 텍스트 초안 작성을 요청할 수 있습니다. 컨텍스트에는 텍스트가 나타날 위치와 전달할 정보가 포함될 수 있으며, 이는 보통 다음 질문 중 하나 이상에 답합니다.

• 이것이 무엇을 하는지.
• 어떻게 사용하는지.
• 왜 중요한지.

검토가 필요한 위치를 알리는 메시지와 함께 검토 요청에서 Technical Writer를 한 번만 태그하는 방안을 고려합니다. 이렇게 하면 검토 회차마다 발생하는 알림 양을 관리하는 데 도움이 됩니다.

MR 검토#

머지 리퀘스트를 생성한 뒤에는 UI 텍스트의 모든 변경과 추가를 Technical Writer가 검토해야 합니다. 여기에는 레이블(버튼, 메뉴, 칼럼 헤더, UI 섹션)이나 마이크로카피·오류 메시지처럼 UI에 표시되는 모든 문구가 포함될 수 있습니다.

UI 텍스트 작성과 검토에 대한 자세한 내용은 Copy That: Helping your Users Succeed with Effective Product Copy를 참고합니다.

파이프라인과 브랜치 이름 지정#

gitlab 및 gitlab-runner 프로젝트의 CI/CD 파이프라인은 문서 변경만 포함된 머지 리퀘스트에서 더 짧고 빠른 파이프라인을 실행하도록 구성되어 있습니다.

omnibus-gitlab, charts/gitlab, gitlab-operator에 문서 전용 변경을 제출할 때 더 짧은 파이프라인을 실행하려면 브랜치 이름을 지정할 때 다음 지침을 따라야 합니다.

gitlab 프로젝트의 다음 파일을 변경하면 일부 코드 테스트가 이 파일을 예시로 사용하기 때문에 긴 파이프라인이 자동으로 트리거됩니다.

• doc/_index.md
• doc/api/settings.md

이 페이지를 편집하면 긴 파이프라인이 코드 MR과 동일하게 나타나지만, 추가 승인은 필요하지 않습니다. 긴 파이프라인에 대한 자세한 내용은 GitLab 프로젝트 파이프라인을 참고합니다.

pre-merge-checks job이 tier-3 파이프라인이나 예측 파이프라인 관련 메시지와 함께 실패하면 다음 단계를 따릅니다.

1. MR에 ~"pipeline::tier-3" 및 ~"pipeline:mr-approved" 레이블을 추가합니다.
2. 새 파이프라인을 실행합니다.
3. 파이프라인이 실행되는 동안 MR을 자동 머지로 설정합니다.

MR을 작업하는 동안 긴 파이프라인 실행을 피하려면 파이프라인을 트리거하지 않고 커밋을 푸시할 수 있습니다. 자세한 내용은 파이프라인 건너뛰기를 참고합니다.

콘텐츠 이동#

콘텐츠를 새 위치로 옮기면서 같은 머지 리퀘스트에서 그 콘텐츠를 편집할 때는 커밋을 분리합니다.

옮긴 콘텐츠의 MR diff는 편집 내용을 분명히 드러내지 않으므로, 커밋을 분리하면 리뷰어에게 도움이 됩니다. 커밋을 분리하면 리뷰어가 첫 커밋 diff에서 위치 변경을 확인하고, 이어지는 커밋에서 콘텐츠 변경을 확인할 수 있습니다.

예를 들어 페이지를 옮기면서 그 페이지의 콘텐츠도 업데이트하는 경우:

1. 첫 커밋: 콘텐츠를 새 위치로 옮기고 필요하면 리다이렉트를 설정합니다. 가능하면 이 커밋에서 깨진 링크를 수정합니다.
2. 이후 커밋: 콘텐츠를 변경합니다. 아직 수정하지 않았다면 깨진 링크를 수정합니다.
3. 머지 리퀘스트: MR 설명과 리뷰어에게 남기는 코멘트에서 각 커밋을 설명합니다.

커밋은 원하는 만큼 추가할 수 있지만, 첫 커밋은 콘텐츠를 옮기기만 하고 편집하지 않도록 합니다.

레이블#

Technical Writing 팀은 이슈와 머지 리퀘스트에 다음 레이블을 사용합니다.

• 변경 유형 레이블. 가장 자주 사용하는 두 가지는 다음과 같습니다.
  • ~"type::feature"
  • ~"maintenance::refactor"를 함께 붙인 ~"type::maintenance"
• stage 및 group 레이블. 예:
  • ~devops::create
  • ~group::source code
• ~documentation 전문 분야 레이블.
• ~Technical Writing 팀 레이블.

문서 머지 리퀘스트 템플릿에는 이 레이블 중 일부가 포함되어 있습니다.

사용 가능한 레이블#

Technical Writer가 작업하는 모든 이슈나 머지 리퀘스트에는 Technical Writing 레이블이 포함되어야 합니다.

작업 유형을 더 세분화하려면 다음 레이블 중 하나 이상을 포함합니다.

• Category:Docs Site: 문서 웹사이트 인프라 또는 코드. 문서 자체와 관련된 이슈에는 필요하지 않습니다. 이 레이블이 붙은 이슈는 Docs Workflow 이슈 보드에 포함됩니다.
• development guidelines: /developer 디렉터리의 파일.
• docs-feedback: 문서 피드백 위젯, 설문 응답, 고객이 생성한 이슈에서 나온 피드백.
• docs-missing: 기능의 문서가 없음. 문서는 GitLab 완료 정의의 일부로, 특정 마일스톤의 기능 제공과 함께 필요합니다. 문서가 없는 원래 기능 MR이나 이슈에 이 레이블을 추가합니다. 이력 추적을 위해 레이블은 그대로 두고, 문서가 완료된 시점은 tw::finished로 표시합니다. 실험 기능에는 적용되지 않습니다.
• documentation: /doc 디렉터리의 파일.
• global nav: 문서 사이트의 왼쪽 내비게이션. docs-gitlab-com 프로젝트에서 사용합니다.
• L10N-docs: Technical Writing 팀의 워크플로 또는 docs.gitlab.com 사이트와 인프라에 영향을 주는 로컬라이제이션 이슈, MR, 에픽.
• release post item: 릴리스 포스트 항목.
• Technical Writing Leadership: OKR처럼 Technical Writing 리더십 팀이 주도하거나 소유하는 작업.
• tw-lead: stage 리드 중 한 명이 주도하거나 그들의 의견이 필요한 MR.
• tw-style: 문서와 UI 텍스트의 스타일 표준.
• UI text: UI 텍스트와 오류 메시지처럼 사용자에게 보이는 모든 텍스트.

그 밖의 문서 레이블로 vale, docs-only, docs-channel이 있습니다. 이 레이블은 선택 사항입니다.

유형 레이블#

제품에 속한 프로젝트의 모든 이슈와 머지 리퀘스트에는 작업 유형 레이블을 붙여야 합니다. 핸드북과 마케팅 사이트 변경에는 작업 유형 레이블이 필요하지 않습니다. 이슈나 머지 리퀘스트에 다음 레이블 중 하나를 추가합니다.

• type::feature
• type::bug
• type::maintenance

자세한 내용은 작업 유형 분류를 참고합니다.

대부분의 문서 작업은 type::maintenance 레이블을 사용합니다. 유지 관리 작업 유형을 더 세분화하려면 다음 하위 유형 레이블 중 하나도 적용해야 합니다.

• maintenance::refactor: 기존 문서의 편집과 개선.
• maintenance::workflow: 린팅·툴링 업데이트나 메타데이터 변경처럼 독자에게 보이지 않는 문서 변경.

예를 들어 CTRT를 위해 페이지를 리팩터링하는 머지 리퀘스트를 열면 type::maintenance와 maintenance::refactor 레이블을 적용합니다. 메타데이터를 수정하는 머지 리퀘스트를 열면 type::maintenance와 maintenance::workflow 레이블을 적용합니다.

워크플로 레이블#

작성자는 이슈나 머지 리퀘스트에서 자신의 작업 상태를 나타내기 위해 이 레이블을 사용할 수 있습니다.

• tw::doing
• tw::finished

콘텐츠를 작성하는 Technical Writer가 보통 tw::doing 레이블을 추가하고, 검토를 수행하는 Technical Writer가 보통 tw::finished 레이블을 추가합니다. 커뮤니티 기여자가 제출한 콘텐츠에서는 Technical Writer가 검토의 일부로 두 레이블을 모두 추가합니다.

워크플로는 다음과 같습니다.

1. 이슈나 머지 리퀘스트가 검토를 위해 작성자에게 배정됩니다.
2. 작성자는 실제로 작업하는 동안 tw::doing 레이블을 추가합니다.
   • 작성자가 1주 넘게 작업을 중단하면 tw::doing 레이블을 제거합니다.
   • 작업을 다시 시작할 때마다 작성자는 tw::doing 레이블을 다시 추가합니다.
3. 이슈나 머지 리퀘스트의 작업이 완료되면 Technical Writer(보통 리뷰어)가 tw::finished 레이블을 추가합니다.
4. 이슈나 머지 리퀘스트가 Closed 또는 Merged 상태가 됩니다.

tw::finished 레이블은 작성자가 직접 닫거나 머지하지 않는 이슈나 머지 리퀘스트에 대해 작업을 마쳤음을 나타냅니다. Technical Writing 팀이 닫거나 머지하는 경우에는 이슈나 머지 리퀘스트의 상태가 범위 지정 tw 레이블 상태보다 우선합니다. 이때 Technical Writer는 tw::finished 레이블을 사용하지 않아도 됩니다.

tw::finished 레이블이 붙은 열린 이슈나 머지 리퀘스트에 추가 작업이 필요한 경우, Technical Writer는 범위 지정 tw::doing 레이블을 다시 추가해야 합니다.

릴리스 포스트#

각 stage 그룹의 Technical Writer는 제품 관리자가 작성한 해당 그룹의 기능 블록 (릴리스 포스트 항목)을 검토합니다.

각 릴리스마다 Technical Writer 한 명이 Technical Writing Lead로도 배정되어 구조 점검과 그 밖의 업무를 수행합니다.

월간 문서 릴리스#

새 GitLab 버전이 릴리스되면 Technical Writing 팀은 버전별 게시 문서를 릴리스합니다.

문서 피드백 및 개선#

특정 코드 변경과 연관되지 않은 문서 변경을 하려면, Technical Writing 팀은 기여자가 MR을 생성하기를 권장합니다.

MR 대신 이슈로 시작한다면 문서 템플릿을 사용합니다. 적용해야 할 레이블은 레이블을 참고합니다.

다음 내용도 포함합니다.

• 마일스톤: 작업이 마일스톤에 예정되기 전까지 Backlog.
• 담당자: 작업이 마일스톤에 예정되기 전까지 None. 이슈 설명이나 코멘트에서 해당 그룹에 배정된 Technical Writer를 멘션(@username)해 알립니다.
• 설명: Docs: 또는 Docs feedback:으로 시작합니다.
• MVC를 제공하기 위한 작업 체크리스트 또는 다음 단계.
• 선택 사항. 이슈가 커뮤니티 기여자에게 적합한 경우: Seeking community contributions과 quick win.

Technical Writer가 작업을 시작하기 전에 개발 팀의 의견이 필요한 이슈라면, 해당 stage와 group의 이슈 생애주기를 따라야 합니다. 이슈 생애주기의 예시는 Plan stage 이슈를 참고합니다.

문서 전용 백로그 이슈 검토 및 분류#

Technical Writer는 이슈 보드를 사용해 담당 그룹의 문서 피드백 및 개선 이슈를 정기적으로 검토하고 분류합니다. 이를 통해 사용자 경험을 개선하는 실행 가능한 이슈에 우선순위를 둡니다.

담당 그룹의 이슈 분류 보드를 만들려면 다음과 같이 진행합니다.

1. Docs only backlog triage - group name이라는 이슈 보드를 생성합니다.

2. 다음 필터 조건을 입력합니다.

   Label=documentation, Label="group::groupname", Label!="type::feature", Label!="type:bug"
   

3. Edit board에서 Show the Open list가 선택되어 있는지 확인합니다.

4. 이슈 보드에서 Create list를 선택하고 레이블을 tw:triaged로 설정합니다.

Project Management 그룹의 예시 보드를 참고합니다.

담당 그룹의 문서 피드백 및 개선 이슈를 검토하고 분류하려면 다음과 같이 진행합니다.

1. 한 달에 한 번, 담당 그룹의 이슈 분류 보드에서 Open 목록에 새 이슈가 있는지 확인합니다.
2. 문서 피드백 및 개선에 설명된 레이블을 적용합니다.
3. 열려 있고 분류되지 않은 이슈 목록을 10건 미만으로 유지하는 것을 목표로 합니다.
4. 분류한 목록을 해당 그룹과 그룹 PM에게 공유합니다.

Technical Writer 검토가 없는 페이지#

/doc/solutions 아래의 문서는 Solutions Architect 팀이 작성, 유지 관리, 교정, 머지합니다.

해커톤#

Technical Writing 팀은 GitLab 해커톤에 참여하고, 때로는 문서 전용 해커톤을 주최합니다.

해커톤용 이슈 생성#

해커톤을 위해 문서 이슈를 만드는 경우가 많습니다. 이 이슈는 보통 문서에 Vale을 실행해 나온 결과를 기반으로 합니다.

1. 전체 문서 세트에 Vale을 실행합니다. GitLab 리포지터리로 이동해 다음을 실행합니다.

   find doc -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../results.txt
   

2. 이슈를 생성합니다. 몇 가지 방법이 있습니다.

   • 스크립트를 사용해 Vale 결과에 나열된 Markdown 파일마다 이슈를 하나씩 생성합니다. 이 스크립트는 Doc cleanup 이슈 템플릿을 사용합니다.
   • Doc cleanup 이슈 템플릿을 사용해 이슈를 하나씩 생성합니다.
   • 이슈 API를 사용해 이슈를 일괄 생성합니다.

이슈에 배정된 레이블이 Doc cleanup 이슈 템플릿의 레이블과 일치하는지 확인합니다.

커뮤니티 기여자에게 이슈 배정#

커뮤니티 기여자에게 이슈를 배정하려면 다음과 같이 진행합니다.

1. Seeking community contributions 레이블을 제거합니다.
2. 코멘트에 /assign @username을 입력해 사용자를 배정합니다. 여기서 @username은 기여자의 핸들입니다.
3. 코멘트에서 해당 사용자를 멘션해, 이슈가 이제 그 사용자에게 배정되었음을 알립니다.

기여자 한 명이 동시에 세 개를 넘는 이슈를 맡지 않도록 제한합니다. 이미 배정된 이슈 중 하나에 MR을 열면 바로 다른 이슈를 배정할 수 있습니다.

해커톤 머지 리퀘스트 검토#

커뮤니티 기여자가 해커톤 머지 리퀘스트를 열면 다음과 같이 진행합니다.

1. 관련 이슈를 확인합니다. MR을 작성한 사용자가 그 이슈에 배정을 요청한 사용자와 같은지 확인합니다.

   • 이슈에 해당 사용자가 없고 다른 사용자가 그 이슈를 작업하겠다고 요청했다면, MR을 머지하지 않습니다. MR 작성자에게 아직 배정되지 않은 이슈를 찾도록 요청하거나 GitLab 개발 기여를 안내합니다.

2. 머지 리퀘스트를 머지하도록 진행합니다.

3. 머지할 때 관련 이슈를 닫는지 확인합니다.

관련 주제#

• Technical Writing 배정
• 검토 및 편집 수준
• 문서 스타일 가이드
• 권장 단어 목록
• 제품 가용성 세부 정보