Markdown으로 작성하고 Word로 전달하는 방법. 시니어 아키텍트의 워크플로우.

Source: Dev.to

갈등: 엔지니어링 vs. 경영

기업 IT에는 근본적인 갈등이 존재합니다:

• 엔지니어는 문서를 코드처럼 작성하고 싶어합니다 (Markdown, IDE에서, Git으로 버전 관리).
• 경영진/클라이언트는 “전문적인” 문서를 원합니다 (Word, 깔끔하게 포맷된, 로고가 포함된).

시니어 아키텍트로서 저는 Microsoft Word의 여백이나 표 정렬에 시간을 빼앗기는 “깊은 작업” 시간을 포기하고 싶지 않습니다. 하지만 원시 .md 파일을 이해관계자에게 보내는 것이 비전문적이라는 것도 알고 있습니다.

해결책은 Word에 굴복하는 것이 아니라 Word로 컴파일하는 것입니다.

도구: 레퍼런스 문서가 있는 Pandoc

Pandoc은 텍스트 포맷을 변환하는 커맨드‑라인 도구입니다. 기업 환경에서의 “핵심 기능”은 --reference-doc 플래그로, 이를 통해 일반 Markdown을 엄격히 포맷된 기업 Word 템플릿에 매핑할 수 있습니다.

워크플로우

튜토리얼: 문서 제작 공장 설정하기

Step 1: Pandoc 설치

• macOS:

  brew install pandoc

• Windows:

  choco install pandoc

Step 2: 레퍼런스 문서 만들기 (템플릿)

1. 회사에서 이미 포맷이 잘 된 문서(올바른 헤더, 폰트, 푸터 로고가 포함된)를 하나 가져옵니다.
2. 모든 내용을 삭제하고 더미 헤더 하나와 단락 하나만 남깁니다.
3. reference.docx라는 이름으로 저장합니다.

Step 3: Markdown으로 작성하기

IDE(VS Code, IntelliJ 등)를 열고 표준 Markdown을 사용해 사양을 작성합니다.

# Architectural Decision Record 001

## Context
We need to migrate the Monolith to AWS.

## Decision
We will use AWS Lambda and Spring Boot SnapStart.

## Consequences
* Cost reduction by 40%
* Cold starts handled by SnapStart

Step 4: 빌드 명령

터미널에서 다음 간단한 명령을 실행합니다:

pandoc input.md -o Final_Report.docx --reference-doc=reference.docx

무슨 일이 일어났나요?
Pandoc은 input.md의 텍스트를 reference.docx에 정의된 스타일에 “부어 넣었습니다”.

• 당신의 # Header 1은 회사 공식 파란색, 16pt 폰트가 적용되었습니다.
• 리스트는 완벽하게 들여쓰기되었습니다.
• 회사 로고는 이미 헤더/푸터에 포함되어 있습니다.

이것이 커리어 해킹인 이유

• 속도: Word보다 Markdown으로 약 3배 빠르게 작성할 수 있습니다.
• 버전 관리: Git으로 변경 사항을 추적합니다. 바이너리 .docx를 검토하는 것은 불가능하지만, Markdown은 검토가 간단하고 Word 문서는 빌드 산출물로 자동 생성됩니다.
• 전문성: Office 365를 한 번도 열지 않고도 비즈니스가 기대하는 정확한 형태의 문서를 전달할 수 있습니다.

열심히 일하기보다 똑똑하게 일하세요. CLI가 포맷팅을 담당하게 하세요.