Heathrow 폐쇄: 공항 관리자가 런던 공항에서 향후 며칠 동안 항공편 운항 중단이 계속될 것이라고 발표
BBC 웹사이트 정보
British Airways는 토요일에 예정된 항공편의 85%가 지연을 동반하여 운항할 것으로 예상했지만, 대부분의 출발은 예상대로 진행되었지만 도착하는 항공편 중 처음 20편의 항공기 중 9대가 취소되었습니다.
Minecraft 새로운 업데이트에 수중 사원이 추가되었습니다.
There has been an error in my update
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
수정하는 데 도움을 주세요.
다양한 작업 환경에서 문서화의 어려움
일상적인 업무와 빈번한 문제 해결로 인해 문서 작성에 시간을 할애하기 어려웠습니다. 엔지니어들은 CI/CD 파이프라인, 모니터링, 자동화, R&D, 고객 지원 및 상세한 시간 기록과 같은 다양한 작업 간에 끊임없이 전환해야 했습니다.
양질의 문서를 작성할 수 있는 기회가 부족했습니다. 저는 일을 제대로 하는 것을 목표로 하지 않습니다.
요구 사항은 다음과 같습니다.
- 동작 로깅
- 이미지, 링크 및 타임스탬프를 포함한 기록 보충
- 초안에서 여러 주제 혼합 방지
- 컴퓨터(모바일 장치 포함)에 관계없이 작업을 시작하고 계속할 수 있도록 하기
- 모든 장치에서 액세스할 수 있도록 초안을 자동으로 저장하기
- 향후 작업 진행 상황 쉽게 복원하기
- 모든 단계에서 초안 공유 가능하도록 하기
처음에는 초안을 프로젝트 문서의 일부로 변환하여 타임라인 단계를 독립적으로 게시하는 것이 목표였습니다. 궁극적으로 발견된 접근 방식은 로컬 사용 범위를 넘어섰고, 조직 전체의 지식 인프라의 사실상의 표준이 되었습니다.
결과적으로 저는 유연하고 확장 가능하며 사용자 중심적인 문서화 시스템을 구축했습니다. 특히 초안의 격리 대신 개방형 토론을 장려하는 결정은 중요합니다. 이는 문서를 품질 수준으로 끌어올리는 속도를 높일 뿐만 아니라 팀 전체를 프로세스에 참여시킵니다.
목표: 문서를 코드로
확장된 서식으로 초안을 작성하고 소프트웨어 코드와 동일한 방식으로 문서 작업을 수행하십시오. 이를 통해 다음과 같은 이점이 있습니다.
- 서식 지정 및 변환 시간 절약
- 온라인 문서 자동 생성
- 오프라인 모드(브라우저 캐시 덕분) - 특히 중요합니다.
- 고객의 폐쇄된 네트워크에서
- 인터넷이 없는 지역에서
"고객들은 이 기능을 높이 평가했습니다."라고 쓰고 싶지만 러시아에서는 유용한 것에 대한 피드백을 얻기가 어렵습니다. 형식이 잘 정착되었다는 것을 이해하기 위해 제가 한 가지 고객이 캐시된 페이지를 1년 동안 사용하고 프로젝트 팀원들이 언급한 새로운 다이어그램과 텍스트를 보지 못하는 이유를 파악하려고 노력하는 것을 보는 데 충분합니다. 그러나 다른 컴퓨터에서 페이지를 열었을 때 인터넷 없이도 자신만 해당 페이지에 액세스할 수 있다는 사실을 알게 되었습니다. 따라서 문서 작성에 투자한 시간은 헛되지 않았습니다.
선택된 기술 스택
기본 형식은 Markdown입니다. 왜냐하면:
- GitLab, YouTrack 및 일부 메신저에서 지원됩니다.
- 모든 최신 LLM에서 정확하게 인식됩니다.
- Word 버전, “떠도는” 이미지 및 호환되지 않는 형식과 관련된 문제를 피할 수 있습니다.
초안에서 다음과 같은 내용을 즉시 얻을 수 있습니다.
- 온라인 버전
- 동일한 스타일로 사이트와 파일 모두에 대한 엄격하고 아름다운 PDF.
현재 문서화 방식
오늘날 문서는:
- Markdown 형식으로 작성됩니다.
- GitLab에 저장됩니다.
- 역할 기반 모델을 통해 모든 직원이 액세스할 수 있습니다.
- 다중 사용자 편집을 지원합니다.
- 자동으로 온라인 버전으로 생성됩니다.
- Docsify 컨테이너가 사용됩니다.
- 매 분마다 업데이트됩니다.
- 각 프로젝트에 대한 3 또는 4 계층 DNS 이름을 통해 인터넷에 사이트가 게시됩니다.
- PDF로 내보냅니다.
- Vue.js를 기반으로 한 단일 스타일을 사용하여 사이트와 파일 모두에 동일한 모양을 제공합니다.
- 다이어그램은 두 형식으로 생성됩니다.
- Draw.io(개요, 복잡한 도식용)
- Mermaid(Markdown 내부에 직접 포함된 인라인)
- 다이어그램 내보내기:
- SVG(주 형식)
- 호환되지 않는 플랫폼의 경우 PNG
- 다이어그램 원본 코드를 파일 내에 포함합니다.
문서화의 3단계 모델 - 그리고 단순화
처음에는 문서화의 세 가지 수준을 고려했습니다.
- 개인적인, 빠르게 변경되는 메모인 초안
- 공동 작업 자료로 자주 변경되는 문서
- 최종 확인된 버전인 정적 문서
그러나 저는 다음과 같이 결정했습니다.
- 초안의 익명성과 격리를 포기합니다.
- 첫 번째 및 두 번째 수준을 Discourse 기반 Wiki 초안으로 통합합니다.
- GitLab + Docsify에서 정적 문서를 유지합니다.
두 번째와 세 번째 수준 간에 자동 동기화가 없더라도 이러한 접근 방식이 실현 가능하다고 생각합니다. 지식 흐름을 단순화하고 동료의 진입 장벽을 낮추고 아이디어를 게시할 준비 상태로 전환하는 속도를 높입니다.
도구 및 형식
| 텍스트 | Markdown (.md) | 주요 작성 형식 |
| 저장 | GitLab | 버전 관리, 검토, 역할 기반 액세스 |
| 온라인 게시 | Docsify(Docker 컨테이너 내) | Git에서 사이트 자동 빌드 |
| 초안 및 토론 | Discourse | 아이디어의 공동 작업 |
| 내장된 다이어그램 | Mermaid | Markdown 내부에 직접 블록 다이어그램 |
| 외부 다이어그램 | Draw.io (.drawio → .svg) | 복잡한 아키텍처 다이어그램 |
| PDF로 내보내기 | Docsify + 단일 Vue 스타일 | 오프라인 액세스 및 고객 전달용 |
그 외
이 계획에는 더 개선할 부분이 있습니다.
- Discourse와 GitLab 간 동기화
- 검토 프로세스를 최종 게시 준비 상태로 전환하는 방식 다듬기
- 링크 무결성 유지
- 게시 자동화
- 발견된 불일치에 대한 피드백 메커니즘 및 수정 사항 알림