Magna-Power의 문서 엔지니어링 개선
모든 현행 제품을 위한 단일 문서 코드베이스, 펌웨어에서 생성되는 명령어 레퍼런스, 그리고 HTML, PDF, AI 도구용 마크다운으로 발행되는 매뉴얼.
Magna-Power는 10개 제품 시리즈에 걸쳐 300,000개 이상의 SKU를 제공합니다. 이러한 폭넓은 라인업은 신중한 장기 계획과 공통 프로그래밍 인터페이스 및 구성 가능한 어셈블리를 위한 의도적인 엔지니어링에서 비롯되었습니다. xGen 플랫폼은 SLx Series MagnaDC 전원공급장치, ALx Series MagnaLOAD DC 전자부하, BDx Module 역류 방지 다이오드 애드온, DBx Module 고안정성 애드온 전반에 걸쳐 하나의 펌웨어 코드베이스로 구동되며, 모든 제품에서 동일한 SCPI 명령어 세트와 동일한 통신 인터페이스를 제공합니다. SL, XR, TS, MT, ML Series MagnaDC 전원공급장치 역시 동일한 펌웨어와 기능을 공유하며, 시리즈 간에 공통 옵션을 제공합니다. 한 시리즈에서 다른 시리즈로 옮겨가더라도 설치 및 프로그래밍 관련 장의 대부분이 동일한 기능을 설명합니다.
엔지니어링을 공유한다면 문서도 공유되어야 마땅하지만, 오랫동안 그렇지 못했습니다. 각 시리즈에는 독립적으로 관리되는 자체 매뉴얼이 있었습니다. 공유 인터페이스에 변경이 생기면 이를 언급하는 모든 매뉴얼에 일일이 복사해야 했고, 이로 인해 내용 불일치가 발생했습니다. 한 매뉴얼에는 수정 사항이 반영되었지만, 다른 매뉴얼에는 어김없이 반영되지 않는 일이 생겼습니다.
Magna-Power의 지속적 개선 문화는 이러한 상황을 더욱 어렵게 만듭니다. 작년 한 해 동안 xGen 개발팀은 7번의 소프트웨어 릴리스에 걸쳐 200건에 가까운 기능 및 수정 티켓을 처리했으며, 고객에게 보이는 모든 변경 사항은 동일한 릴리스에서 올바른 매뉴얼에 정확하게 기술되어 반영되어야 합니다. 누군가 각 변경 사항을 알아차리고 여러 문서를 수작업으로 수정하는 방식에 의존하는 프로세스는 확장될 수 없습니다. 이 프로세스가 뒤처지면 그 사실을 알게 되는 쪽은 고객입니다.
그래서 저희는 문서를 엔지니어링 시스템으로 재구축했습니다. 하나의 코드베이스, 공유 구성 요소, 자동화된 빌드, 버전이 관리되는 릴리스, 그리고 펌웨어 자체에서 생성되는 명령어 레퍼런스로 이루어진 시스템입니다. 이번 달 Snapshot 75 릴리스를 통해 모든 현행 제품 매뉴얼이 이 시스템으로 통합됩니다.
단일 소스, 모든 제품이 공유
각 제품 시리즈에는 자체 문서 프로젝트가 있으며, 모든 프로젝트는 Git 서브모듈로 고정된 여러 공유 구성 요소를 가져옵니다. 이 구성 요소로는 빌드 구성 및 도구, 웹 HTML 테마, 그리고 해당 제품군과 제품 세대에 공통되는 콘텐츠 라이브러리가 있습니다.
공유 콘텐츠 라이브러리는 중복을 피하도록 설계되었습니다. 예를 들어 수냉 관련 장은 과거에 TS Series 매뉴얼에 있었고 다른 매뉴얼에는 편집된 사본이 있었습니다. 이제는 한 곳에만 존재하며, TS, SL, ML 매뉴얼이 모두 이를 포함합니다. ML Series 냉각수 바이패스 커넥터와 같은 시리즈별 세부 정보는 같은 페이지에 있으며, 해당되는 매뉴얼에만 표시됩니다. 공통 콘텐츠에 대한 수정 사항은 다음 빌드에서 세 매뉴얼 모두에 반영됩니다.
Magna-Power 팀은 엄격한 빌드 방식도 채택했습니다. 경고를 오류로 처리하므로, 깨진 상호 참조나 누락된 그림이 있으면 죽은 링크로 배포되는 대신 릴리스가 중단됩니다. 이 제약 덕분에 공유 콘텐츠를 수정하더라도 관련된 다른 매뉴얼이 조용히 깨지는 일이 없습니다.
펌웨어에서 생성되는 명령어 문서
모든 SCPI 명령어는 펌웨어 소스에 구조화된 데이터로 정의되어 있습니다. 여기에는 구문, 매개변수와 그 범위, 쿼리 형식, 설명, 예제가 포함됩니다. 펌웨어 빌드는 이 테이블에서 명령어 파서를 생성하고, 문서 빌드는 동일한 테이블에서 Programming 장을 생성합니다.
문서 생성기는 어떤 제품군을 대상으로 빌드하는지 알고 있습니다. 예를 들어 전원공급장치에는 DC 출력을 활성화하는 명령어가 있고, 전자부하에는 DC 입력을 활성화하는 명령어가 있습니다. 하나의 정의 세트로 각 제품 유형에 맞는 올바른 레퍼런스가 생성되며, 해당 제품이 실제로 구현한 명령어만 나열됩니다.
그 효과는 처리 시간에서 나타납니다. 엔지니어가 명령어에 매개변수를 추가할 때 수정하는 정의는 하나뿐입니다. 다음 펌웨어 빌드는 해당 매개변수를 받아들이고, 문서 빌드는 엔지니어가 직접 작성한 설명과 예제를 사용하여 이를 기술합니다. 이러한 펌웨어 기반 문서는 코드 리뷰 프로세스의 일부가 되어 정확성을 보장하며, 제3자에게 넘기는 인수인계 과정이 필요 없습니다.
지속적 통합 워크플로로 빌드 및 릴리스
이 빌드 프로세스는 펌웨어, MagnaCTRL 소프트웨어, 그리고 테스트 및 교정 도구를 컴파일하는 자체 지속적 통합 서버에서 실행됩니다. 문서는 다른 빌드 산출물과 마찬가지로 고유한 버전으로 태그가 지정되며, 해당 문서가 설명하는 펌웨어와 동일한 릴리스 스냅샷에 함께 번들로 포함됩니다. 이번 달에 릴리스된 Snapshot 75는 펌웨어 0.084를 태그가 지정된 SLx, ALx, BDx, DBx 매뉴얼과 짝지어 제공합니다.
한 번의 빌드로 하나의 소스에서 세 가지 출력물이 생성됩니다. 웹 매뉴얼용 HTML, 고객이 인쇄하여 프로젝트와 함께 보관하는 매뉴얼용으로 LaTeX를 통해 조판되는 PDF, 그리고 대규모 언어 모델용 마크다운입니다. 하나의 공유 LaTeX 레이아웃이 모든 매뉴얼의 타이포그래피, 번호가 매겨진 그림과 표, 상호 참조를 관리하며, 치수 도면을 페이지에 맞게 조정하고 명령어 이름이 줄바꿈 시 하이픈으로 끊어지지 않도록 하는 것까지 포함합니다.
웹 매뉴얼
웹 매뉴얼에는 magna-power.com과 어울리도록 자체 개발한 새로운 테마도 적용되었습니다. 기술 도면은 모두 벡터 그래픽이며, PDF를 다운로드하지 않고도 클릭하면 라이트박스에서 적절하게 확대 및 축소되도록 설계되었습니다. 코드 예제에는 구문 강조와 복사 버튼이 있습니다. 왼쪽 내비게이션은 스크롤에 따라 현재 위치를 추적합니다. 다크 모드에서는 선화 다이어그램을 반전시켜 투명 배경에 검은색으로 그려진 도면도 읽기 쉽게 유지하며, 로고와 사진은 그대로 둡니다. 경고(Warning) 및 주의(Caution) 콜아웃에는 두 모드 모두에서 표준 색상의 ISO 7010 안전 경고 기호가 표시됩니다. 글꼴은 자체 호스팅되므로 오프라인 사용을 위해 매뉴얼을 저장할 때도 일관된 모습을 유지할 수 있습니다.
문서 버전 전환기
지금까지는 제품 매뉴얼의 최신 버전만 온라인에 게시되었고, 이전 빌드는 덮어쓰기되었습니다. 이전 펌웨어를 기준으로 시스템을 시운전했고 당시의 매뉴얼이 필요하더라도, 이를 (쉽게) 구할 방법이 없었습니다.
이제 각 매뉴얼에는 Documentation Version 전환기가 있습니다. 최신 릴리스는 제품의 기존 주소에 그대로 유지되며, 이전의 모든 릴리스는 보관됩니다. 지속적 통합 서버는 빌드할 때마다 제품 문서 루트에 버전 매니페스트를 작성하고, 전환기는 페이지가 로드될 때 해당 매니페스트를 읽습니다. 따라서 보관된 페이지에는 해당 릴리스 이후에 발행된 최신 버전을 포함한 모든 버전이 표시됩니다. 버전을 선택하면 해당 버전에 같은 페이지가 있는 경우 그 페이지로 이동하고, 없는 경우 해당 버전의 첫 페이지로 이동합니다. 보관된 페이지에는 현재 보고 있는 버전을 알려주는 배너가 표시되며, 최신 버전으로 연결되는 링크도 제공됩니다.
문서 버전은 펌웨어와 별도로 번호가 매겨지며, 릴리스 스냅샷을 통해 서로 짝지어집니다. 아카이브는 이번 릴리스부터 시작되므로 이전 빌드는 제공되지 않을 수 있습니다.
AI 어시스턴트에게 전달할 수 있는 매뉴얼
엔지니어들은 점점 더 AI 어시스턴트에게 매뉴얼을 건네주고 테스트 스크립트 초안을 작성하거나 상태 레지스터를 해석해 달라고 요청하고 있습니다. 아래 예시와 같이 PDF 텍스트 추출은 읽기 순서와 표 구조를 훼손할 수 있습니다. 이 예시는 일반적인 Python 라이브러리인 pdftotext를 사용하여 PDF의 한 페이지를 변환한 것입니다.
이제 모든 매뉴얼은 llms.txt 규약에 따라 일반 텍스트로도 발행됩니다. 매뉴얼 루트의 색인, HTML 옆에 나란히 제공되는 모든 페이지의 Markdown 렌더링, 그리고 매뉴얼 전체를 하나로 합친 파일이 그것입니다. Markdown 형식은 제목, 표, 코드 블록이 그대로 유지되도록 보장합니다. 위험 콜아웃은 이제 레이블이 지정된 블록으로 전달되므로, 설치 절차를 요약하는 어시스턴트도 사람이 보는 것과 동일한 경고를 확인합니다. 텍스트 파일은 HTML과 동일한 빌드에서 생성되므로 항상 동기화된 상태를 유지합니다. 이 단계가 실패하면 텍스트 파일 없이 매뉴얼을 배포하는 대신 전체 빌드가 실패합니다.
문서를 제품의 일부로 다루면 각 개선 사항을 이를 필요로 하는 모든 매뉴얼에 반영하고, 그 내용이 설명하는 기능과 함께 릴리스할 수 있습니다. 고객은 자신의 장비에 대해 일관된 안내를 받을 수 있으며, 작업에 가장 적합한 버전과 형식으로 제공받습니다.
동일한 소스로 빌드된 SLx Series 레퍼런스 문서 예시: