Shapezo를 사용한 신호탑 지식 모델링: 통신 자산을 위한 구조화된 콘텐츠 파이프라인

대부분의 통신 문서는 지루한 이유로 실패합니다. 즉, 구조적인 것들에 대한 비구조화된 산문이기 때문입니다. 신호탑 현장은 그래프입니다. 마스트(mast), 시설 구역(compound), 전력 공급 장치(power feed), 백홀 링크(backhaul link), 서비스 폴리곤(service polygon), 그리고 유지보수 일정으로 구성되어 있으며, 이들 사이에는 관계가 존재합니다. 이를 Word 문서로 저장하면 그래프 구조를 잃어버리고 매 분기마다 수동으로 재도출해야 합니다.

Shapezo의 해결책은 현장 자체를 먼저 모델링하고 산문을 나중에 렌더링하는 것입니다. 콘텐츠는 스키마(schema)가 있는 타입화된 객체가 되고, 아티클은 빌드 아티팩트(build artifact)가 됩니다. 본 포스트에서는 이 모델과 파이프라인을 설명합니다.

사이트 스키마 (The site schema)

Shapezo의 사이트 객체는 의도적으로 작습니다. 네 가지 엔티티가 거의 모든 타워를 다룹니다:

site:
  id: tower-north-ridge-04
  mast:
...

두 필드는 Shapezo 고유의 부분이므로 주목할 만합니다. narrative.shape는 고정된 열거형(enum)(vertical_journey, day_in_life, negotiation, service_record)에서 아티클 구조를 선택합니다. anchor_details는 산문이 깊이 있게 다룰 수 있는 한두 가지 기술적 세부 사항의 이름을 지정합니다. 나머지 모든 것은 요약 수준으로 유지됩니다. 이 단일 제약 조건이 생성된 아티클을 읽기 쉽게 유지하는 비결입니다.

모델에서 산문 렌더링하기 (Rendering prose from the model)

렌더러는 각 내러티브 형태(narrative shape)별로 템플릿을 가집니다. 각 템플릿은 스키마 경로에 바인딩된 슬롯(slots)으로 구성된 섹션의 연속입니다. 자유 형식(free-form) 부분이 없습니다. 만약 슬롯에 데이터가 없다면, 해당 섹션이 조용히 사라지는 대신 눈에 보이는 TODO 마커를 렌더링합니다. 따라서 공백이 운영 단계에서 발견되는 것이 아니라 검토 과정에서 드러나게 됩니다.

def render(site, shape):
    template = TEMPLATES[shape]
    out = []
...

출력이 주어진 스키마에 대해 결정론적(deterministic)이기 때문에, 변경 사항 비교(diffs)가 의미를 가집니다. 스키마 변경은 코드 검토 과정에서 깔끔한 아티클 diff로 나타나며, 이는 인프라 지식 변경이 검토되어야 하는 정확한 위치입니다.

자산 파이프라인 (The asset pipeline)

이미지는 장식(decoration)이 아니라 계약(contract)을 가진 빌드 입력물로 취급됩니다. 각 현장(site)은 context, equipment, consequence의 세 가지 슬롯을 선언하며, 파이프라인은 수집 과정에서 기하학적 구조와 가중치(weight)를 강제합니다:

# 16:9 크롭, 720p, 목표 ~200KB JPEG
magick in.png -gravity center -crop 16:9+0+0 -resize 1280x720 out.jpg

가중치 목표는 들리는 것보다 더 중요합니다. 현장 안내 자료(Site guides)는 농촌 지역의 셀룰러 링크를 통해 읽히기 때문에, 바로 그곳이 문서화가 가장 무겁고 네트워크 상태가 가장 나쁜 곳입니다. 이미지당 200KB 예산은 전체 3개 장면 가이드가 메가바이트 하나를 넘지 않게 유지합니다.

아래의 리깅 상세 샷(rigging detail shot)은 consequence와 인접한 에셋의 좋은 예시입니다. 프레임에 사람이 필요하지 않아도 마스트의 작동 인터페이스를 문서화합니다.

쉘터(shelter) 샷이 부하를 지탱하는 이유 (load-bearing one)

세 가지 슬롯 중 equipment가 파이프라인 비용을 지불하는 부분입니다. 이 복합 시설은 분기별로 바뀌며 결함(faults)이 존재하는 곳이므로, 쉘터 이미지는 변경 감지 기준선(change-detection baseline) 역할을 합니다. 이를 스키마에 포함하면 비교 작업이 고정된 각도에서의 이미지 git diff가 되며, 고고학 프로젝트가 아닙니다.

얻게 되는 것 (What you get)

모델링을 먼저 하고 렌더링은 나중에 하게 되며, 세 가지 변화가 생깁니다. 문서화는 검토 가능(reviewable)해지는데, 스키마 변경이 아티클 diff를 생성하기 때문입니다. 완전(complete)해지는데, 필수 슬롯에 값이 없으면 명확하게 오류를 발생시키기 때문입니다. 그리고 저렴(cheap)해지는데, 현장 업데이트가 산문 재작성 대신 네 개의 YAML 블록 편집으로 끝나기 때문입니다.

Shapezo는 CMS(콘텐츠 관리 시스템)도 아니고 정적 사이트 생성기(static site generator)도 아닙니다. 이는 콘텐츠를 작성하기 전에 그 형태를 결정하는 학문이며, 그 결정을 강제할 수 있는 최소한의 도구들만을 제공합니다. 기반 객체가 이미 잘 정의된 그래프인 신호탑의 경우, 이 학문적 접근 방식은 거의 불공평할 정도의 레버리지를 제공합니다.