방어적 글쓰기(커뮤니케이션)의 몇 가지 기술

방어는 과거에 받은 공격의 기억에서 온다. 그것은 생존 본능이다. 특허 명세서나 법원 판결문처럼 극도로 방어적인 문서들도 결국 같은 원리에서 만들어진다.

글쓰기는 정보나 감정을 전달하는 것이 원래 목적이다. 조직에서 만들어 내는 많은 문서는 겉으로는 정보를 전달하는 것 같지만, 결국은 책임을 관리하기 위한 것이다. 이런 목적에서 안전하게 글을 쓰는 방식을 방어적 글쓰기라고 불러 보자.  '세 시간 내로 보내 주세요'와 같은 갑(甲)의 요청에 대응하는 것은 글쓰기가 아니라 작성된 글을 전달하는 기술에 해당하지만, 이것도 포함하여 논하기로 한다.

첫 번째 기술은 매우 널리 통용되는 것으로, 제출 시한에 임박해서 보내기이다. 표면적으로는 작성에 공을 들이느라 이렇게 되었다고 변명하지만, 대부분의 경우 다 만들어 놓고도 일부러 늦게(그러나 기한 내에) 보내는 것이다. 문서를 너무 일찍 보내면 검토와 질문이 이어질 가능성이 매우 높기 때문이다.

두 번째 기술은 표현을 적절히 모호하게 만드는 것이다. 상세하거나 전문적인 용어가 들어가면 추가 설명을 요청하거나 꼬투리를 잡히기 쉽다. "모든 여건을 감안해 본다면", "일반적으로", "필요하다면"과 같은 표현은 문장도 온건하게 만들고 책임의 범위도 흐려진다.

세 번째 기술은 서론을 길게 만드는 것이다. 본론에 들어가기 전 긴 배경 설명이 들어가면 읽는 사람은 핵심 메시지를 잡아채서 논쟁하기 어려워진다. 결론을 가장 나중에 말하는 우리말의 특성과 가장 잘 어우러지는 글쓰기 기법이다. 이 기술은 글이 아니라 프레젠테이션에서도 써먹을 수 있다. 그러나 너무 노골적으로 서론을 길게 끌면, '결론부터 말해봐요'라는 공격에 직면할 수 있다.

글을 요청하는 갑(甲)은 이런 기술을 구사하기도 한다. 원래 이틀 뒤에 받아도 충분한 글을 일부러 촉박하게 내일까지 달라고 요청한다. 이틀 후에 제출해도 된다는 것은 물론 철저히 숨긴다. 을(乙)이 애를 먹고 있음을 너무나 뻔하다. 이윽고 내일이 되었다. 갑은 마감 직전에 이렇게 알린다. "힘드세요? 그러면 시간 하루 더 드릴께요". 을은 갑이 어렵사리 융통성을 발휘해 준 것으로 착각하고 오히려 고마워한다.

을에게 마감일을 어떻게 통보할까? 금요일 퇴근 전? 월요일 출근 직전? 이를 결정하는 데에도 치열한 눈치작전이 벌어지고, 그 결과에 따라 을의 주말은 평온한 휴식이 될 수도 있고 초과 근무가 될 수도 있다. 주가에 영향을 미칠 만한 좋지 않은 뉴스를 금요일 오후에 내보내는 것('Friday afternoon news dump'), 인사발령을 금요일 오후에 내는 것... 다 이유가 있다. 방어적 글쓰기와 함께 엮어서 방어적 커뮤니케이션 전술이라고 불러도 되겠다.

전형적인 방어적 글쓰기 사례는 뭐가 있을까? 보험 약관, 특허 명세서, 법원 판결문, 감사 대응 보고서, 기업의 리스크 공시, 의료 동의서/임상시험 설명문, 계약서 등.

이러한 기술을 너무나 잘 알고 있으며 업무 중 매우 이를 적절하게 구사하고 있는 당신은? 자랑스러워하지 말라. 조직 혁신의 측면에서는 매우 어두운 곳에 속한 사람일지도 모른다.

자작 43 power pentode 진공관 앰프의 망가진 전원 스위치 관련 정보 알아보기

자작 43 power pentode SE amplifier의 망가진 전원 스위치의 작동 현황 동영상을 살펴보자. 매일 작동하지도 않는 조건에서 겨우 5~6년 정도 사용했는데 벌써 망가진다니 몹시 실망스럽다. 

패널에 뚫은 스위치 고정용 구멍은 원형이었나, 혹은 사각형이었나? 상판 설계 당시 LibreCAD로 그렸던 도면을 찾아서 살펴보았다. 직경 20.3mm의 구멍을 그린 것으로 보아 직경 20mm의 스위치를 썼던 것으로 여겨진다. 이런 종류의 램프형 스위치(원형)는 매우 구하기 쉽다. 

2020년에 이맘때에 그린 도면에는 직경 20.3mm의 구멍을 뚫어서 전원 스위치를 고정했었다. 

사실 보다 정확하게는 다음과 같이 가공을 했어야 한다. 원주 양쪽에 사각 홈을 파도록 도면을 그리려면 조금 더 성가시다.

자료 원본 출처는 여기.

교체의 편의성을 생각한다면 전원 스위치의 단자에 전선을 납땜하는 것보다 납작한 모양의 압착형 커넥터를 쓰는 것이 더 나을 것이다. 한국에서는 흔히 PG (암)단자라고 하는데 정식 영문 명칭은 스페이드(spade, 날이 넓적한 삽) 단자라고 하는데, 실제 세계에서는 여기에 물리는 male 단자가 삽 모양에 더 가깝다.

절연체의 색깔은 연결에 사용할 전선의 굵기를 나타낸다.

일반적인 전원 스위치의 단자에 맞는  PG 단자의 규격(폭)은 4.8mm인 것으로 파악되었다. 오늘도 알리익스프레스에서 약간의 쇼핑을 해야 되겠다.

시름이 깊어질수록 회로도의 완성도는 높아지고...

오늘의 (Nano Ardule for) FluidCanvas의 회로도는 더욱 완성도가 높아졌다. 이를 가능하게 만드는 추진력은 업무 스트레스! 회로 설계를 마친 뒤 심야 달리기까지 하고 오면 머리가 맑아지고 선한 생각으로 가득 차는 것 같다.

어제까지는 패널용 MIDI IN/OUT 커넥터(DIN-5, female)를 쓸 생각이었다. 그러려면 기판에는 별도의 커넥터가 필요하다. 하지만 PCB에 직접 고정하는 DIN-5(180도) 커넥터를 쓰면 제작이 훨씬 쉽지 않겠는가? 대신 기판 면적은 훨씬 많이 차지하는 부작용은 감수해야 한다. 아두이노 나노의 RX/TX 핀과 MIDI IN/OUT 회로를 잇고 끊을 때에도 스위치가 아니라 3핀 헤더와 점퍼션트를 쓰기로 하였다. 단순한 것이 최고다. 회로도를 수정하고 전기적 연결이 완전한지를 알아보기 위해 Electrical Rules Check를 마쳤다. 

그러나 KiCad 기본 라이브러리에는 PCB용 DIN-5 커넥터(horizontal)의 부품 심벌은 있지만 footprint가 없다. 현재 기본 배포되는 것은 DIN41612 커넥터의 그것만 포함한다. 인터넷에서 검색을 통해 찾은 커스텀 풋프린트는 기판에 수직으로 고정하게 만든 것이 전부라서 별 소용이 없었다. KiCad 포럼에서는 mini DIN-3에서 DIN-8 커넥터의 풋프린트와 3D 모델을 만들어 공개한 사람도 있었다(링크).

검색을 거듭한 결과 DIN5_MIDI.kicad_mod라는 파일을 발견하였다. 정말 고마운 자료이다. 이것을 적절히 수정하면 될 것이다. 풋프린트는 top view임을 잊지 않는다면 custom footprint를 만들 때 치명적인 실수를 줄이게 될 것이다.

어두운 바탕에 찍힌 점들... LibreCAD에서 익숙하게 보던 화면이다.

위 풋프린트 그림에는 서로 다른 색깔로 표시된 세 층의 레이어가 보인다. 두꺼운 빨간색 도넛으로 표현된 것은 바로 구리로 만들어진 패턴에 해당하는 레이어다. 바로 여기에 부품의 다리가 납땜되는데, 윗면인 F.Cu와 아랫면인 B.Cu가 있다. 흰 선은 부품의 외곽선에 해당하는 실크스크린 레이어(F.SilkS)로서 PCB 위에 인쇄된다. 가장 바깥쪽의 보라색 선은 부품 배치 공간을 규정하는 레이어인 F.CrtYd(courtyard)이다. 여기에서는 정확한 부품 외형에 해당하는 패브리케이션 레이어(F.Fab)가 생략되었다.

다음의 사례는 기본 라이브러리에서 고른 직경 3mm LED의 풋프린트이다. 회색으로 표현된 F.Fab이 보인다.

위에서 소개한 DIN5_MIDI.kicad_mod를 그대로 사용할 수는 없다. 부품마다 외형 치수가 조금씩 다르기 때문이다. 따라서 AliExpress에서 실물 부품을 먼저 주문하였다. 이를 버니어 캘리퍼스로 정밀하게 측정한 뒤 DIN5_MIDI.kicad_mod를 수정하면 된다. KiCad 튜토리얼에서 Custom Symbol과 Footprint를 생성하고 수정하는 법을 소개하고 있다. 그것도 번거로우면 부품 도면을 ChatGPT에 밀어 넣은 뒤 파일을 만들어달라고 해 보면 된다.

반신반의하면서 SparkFun Electronics에서 제공하는 데이터시트(PDF)를 업로드해 보았다. 파일에서 필요한 부분만 잘라내어 다각도로 판단하며 해석하는 것도 인공지능의 몫이다. 도면의 레이아웃을 이해하는 데 한참의 시간을 소비하였다. 약 5분 20초 후 생성된 결과물을 확인해 보자.

---

이 풋프린트는 업로드하신 4UCON 도면의 Recommended P.C.B. Layout (Top View)를 기준으로, 7개 홀 위치를 반영하여 만들었습니다. 핀 좌표는 도면에 제시된 2.8 mm, 12.5 mm, 15 mm, 세로 10 mm / 14.6 mm 치수를 사용했고, 드릴은 7×Ø1.5 mm로 설정했습니다.

참고로 넣어 둔 항목은 다음과 같습니다.

• 패드 번호: 1~5, 접지 셸은 E
• 레이어: F.SilkS, F.Fab, F.CrtYd
• 외곽선은 도면의 본체 치수를 바탕으로 한 단순화된 외형

주의할 점은 다음과 같습니다.

• 이 파일은 홀 위치 중심의 실사용 풋프린트로는 바로 써볼 수 있지만,
• 실크 및 외곽 형상은 도면 해상도 한계로 인해 일부를 단순화했습니다.
• 실제 구매한 부품과 100% 맞추려면, 부품 실측 후 실크와 courtyard를 한 번 더 다듬는 것이 안전합니다.

원하시면 다음 단계로 바로 이어서 “패널 전면 기준으로 보드 엣지 정렬까지 고려한 버전” 또는 “DIN-5_MIDI_THT_horizontal.kicad_mod” 같은 원하는 파일명 버전
으로 다시 정리해 드릴게요.

ChatGPT가 부품 데이터시트를 이용하여 생성한 KiCad 풋프린트 파일.

---

정말 놀랍다. 이를 바탕으로 실측을 한 뒤에 '핀 2와 3의 간격을 1mm 더 벌려 줘'라고 지시해도 될 것이다. 

회로도는 마무리하였지만 실제 보드 아웃라인을 만들고 부품을 배치하여 라우팅을 한 뒤 DRC(Design Rule Check)까지 거쳐서 PCB 설계를 완성하려면 더 많은 공을 들여야 한다. 오늘 주문한 커넥터가 어서 배송되어 측정을 거쳐 정확한 수치를 얻은 뒤 PCB 설계를 마치게 되기를 기대해 본다.  

PubMed에서 시작되는 힘 — 데이터 리포지터리의 진짜 교훈

생명과학 데이터 인프라를 이야기할 때 많은 사람은 먼저 데이터의 규모를 떠올린다. 몇 PB의 데이터를 저장하고 있는가, 몇 개의 데이터셋이 등록되어 있는가 같은 지표가 흔히 등장한다. 그러나 세계에서 가장 영향력 있는 생명과학 정보 인프라를 운영하는 NCBI (National Center for Biotechnology Information)의 사례를 보면, 데이터의 양만으로는 그 성공을 설명하기 어렵다.

NCBI의 진짜 힘은 데이터의 규모가 아니라 지식 접근 구조에 있다. 그리고 그 구조의 출발점은 바로 PubMed이다.

생명과학 연구자는 거의 예외 없이 PubMed에서 탐색을 시작한다. 새로운 연구 주제를 찾을 때도, 특정 유전자나 질병에 대한 정보를 확인할 때도, 가장 먼저 찾는 것은 논문이다. PubMed에서 논문을 검색하고, 논문을 읽다가 관련 유전자나 데이터셋을 확인하면 자연스럽게 NCBI의 데이터베이스로 이동하게 된다.

이 과정은 매우 자연스럽게 이루어진다. 논문 페이지에는 관련 데이터로 연결되는 링크가 이미 준비되어 있기 때문이다. 그 결과 연구자는 다음과 같은 흐름을 경험하게 된다.

논문 → 데이터 → 분석

이 단순한 흐름이 바로 NCBI 시스템의 핵심이다. 논문을 읽다가 클릭 몇 번으로 서열 데이터나 발현 데이터로 이동할 수 있고, 다시 분석 도구로 이어질 수 있다. NCBI는 데이터를 단순히 저장하는 것이 아니라 논문과 데이터를 연결하는 지식 네트워크를 설계하였다.

많은 데이터 리포지터리가 간과하는 부분이 바로 이 지점이다. 데이터 플랫폼을 구축할 때 흔히 강조되는 것은 데이터의 수와 저장 용량이다. 그러나 연구자의 실제 행동을 생각해 보면, 연구자는 데이터베이스에서 출발하지 않는다. 연구자는 항상 논문에서 출발한다.

따라서 데이터 리포지터리가 연구 생태계에서 의미를 가지려면 데이터 자체보다 데이터에 도달하는 경로가 중요하다.

K-BDS에 주는 정책적 시사점

이 문제는 국내 바이오 데이터 정책에서도 생각해 볼 만하다. Korea BioData Station (K-BDS) 같은 데이터 플랫폼의 성과는 종종 다음과 같은 지표로 평가된다.

• 등록된 데이터셋 수
• 저장 용량
• 데이터 업로드 건수
• K-BDS에 데이터를 등록하여 그 accession number를 인용했거나, 또는 K-BDS에 이미 등록된 데이터를 재활용하여 출판한 논문의 수(data announcement 논문도 포함할 수 있으나 임팩트는 다소 낮게 평가된다)
  

하지만 이러한 지표만으로는 데이터 인프라의 실제 가치를 충분히 설명하기 어렵다.

데이터가 연구 생태계에서 실제로 사용되기 위해서는 다음과 같은 조건이 필요하다.

• 연구자가 데이터를 쉽게 발견할 수 있어야 한다
• 데이터가 연구 논문과 연결되어 있어야 한다
• 데이터가 분석 도구와 연결되어 있어야 한다

즉 데이터 플랫폼의 핵심은 저장 공간이 아니라 지식 접근 구조이다.

NCBI가 보여주는 교훈은 명확하다. 데이터 인프라는 단순한 데이터 저장소가 아니라 연구자가 지식에 접근하는 경로를 설계하는 시스템이다. PubMed는 그 입구 역할을 하며, 다양한 데이터베이스는 그 내부 구조를 구성한다.

결국 NCBI의 성공은 데이터의 양이 아니라 논문을 중심으로 한 지식 인덱스 구조에서 비롯된다.

데이터 정책을 논할 때 종종 잊히는 사실이 하나 있다.

데이터는 모은다고 해서 자동으로 활용되지 않는다.

데이터가 작동하려면 연구자가 그것을 발견할 수 있어야 하고, 논문과 연결되어 있어야 하며, 분석으로 이어질 수 있어야 한다.

NCBI는 그 구조를 만들어 냈다.

그리고 그 모든 것은 PubMed에서 시작된다.

AI 시대가 도래함으로써 연구자가 직접 논문을 찾고 데이터를 (재)분석하는 수고를 덜게 되었고, 모든 리포지토리는 보유 데이터를 얼마나 많이 AI-ready 형태로 가공하여 제공하고 있는가로 평가를 받게 될 것 같다. 특히 정부의 지원으로 운영되는 데이터 인프라의 경우 그러한 압박감은 더욱 심하다. 도대체 언제부터 데이터 인프라의 가장 중요한 목적이 AI에게 먹이를 제공하는 것이 되었는가?

그러나 이 질문에는 신중하게 답변해야 한다. 데이터 리포지터리의 역할은 AI 학습용 데이터 공급자로 축소되어서는 안 되기 때문이다. AI 모델은 데이터를 소비하지만, 데이터의 의미와 맥락은 여전히 연구 공동체 속에서 형성된다. 논문, 실험 설계, 데이터 생성 과정, 데이터 해석의 논리 등은 데이터 파일만으로 대체되기 어렵다.

다시 말해서 AI 시대에도 여전히 중요한 것은 지식 생태계의 구조이다. 'AI 학습에 필요한 데이터와 컴퓨팅 자원을 확보하는 것이 무엇보다도 가장 시급해'  'AI가 이제 연구도 알아서 해 주니까 나는 연구 소비자처럼 이를 이용만 하겠어' 이런 주장과 논리 속에서 중요한 것을 잃어서는 안 된다.

데이터는 AI가 읽을 수 있어야 하지만, 지식은 여전히 연구 공동체 안에서 만들어지기 때문이다.

---

이 글은 정해영의 아이디어를 바탕으로 AI(ChatGPT)의 도움을 받아 작성되었습니다. 본 텍스트는 Creative Commons Attribution 4.0 International(CC BY 4.0)라이선스로 공개됩니다. 출처를 표시하는 조건으로 누구나 자유롭게 이용·수정·재배포할 수 있습니다. 정확성에 대한 보증이나 법적 책임은 제공되지 않습니다.

KiCad로 그린 첫 회로도

KiCAD가 아니라 KiCad라고 쓰는 것이 관행인 것 같다. KiCad는 전자회로 및 PCB 설계에 특화된 오픈소스 EDA(Electronic Design Automation)이다. 공식 웹사이트는 https://www.kicad.org/.

KiCad와 같은 종류의 프로그램은 PCB를 설계하여 주문하려면 피할 수 없는 선택이다. LTspice와 Fritzing에 이어서 드디어 오늘을 기하여 KiCad에 입문하게 되었다. LibreCAD도 약간은 다룰 줄 안다. 취미 "메이커"가 알아야 하는 필수 소프트웨어를 조금씩은 다 경험하게 된 셈이다. 이러다가 3D 프린팅 도면까지 만들게 되는 것은 아닌지 모르겠다.

페놀 만능기판에 배선 실수와 납땜 불량을 감수하고 얼기설기 만들었던 Nano Ardule을 올해에는 PCB에 옮겨 보고자 ChatGPT에게 step-by-step tutorial을 요청한 뒤 이를 따라서 일단 회로도부터 만들어 보았다. NET LABEL의 개념을 제대로 이해하고 커넥터 배치에 신경을 써야 한다. 특히 아두이노 관련 PCB 설계에서는 커넥터 위치 결정이 절반 이상을 차지한다고 한다. 회로도 설계 단계에서는 일단 Conn_01x05과 같이 1-row의 단순한 것으로 그려 놓았지만, 조만간 어떤 커넥터를 써야 할지 결정을 해야 한다. 이제는 더 이상 프로토타입을 만드는 것이 아니기 때문에, 핀헤더를 납땜해 놓고 듀폰 케이블로 대충 연결할 수는 없다. 작년에 쓴 글 '세상의 모든 커넥터'를 다시 읽으면서 공부를 해야 되겠다. 터미널 압착기(SN-2549 크림핑 툴)를 사 놓기를 잘했다.  

아직 검증되지 않은 회로도. 회로 자체는 작년에 실물로 입증하였으나, KiCad로 옮겨 그리는 과정에서 많은 실수가 숨어있을 것이다.

회로 자체는 대단히 간단(?)하다. 여기까지는 아마도 매우 쉬운 과정이었을 것이다. 실제 부품에 맞는 footprint를 고르는 일이 더 걱정이다. JST냐 Molex냐... 갖고 있는 부품 재고를 되도록 활용하고 싶은데 핀 수가 맞는지 모르겠다. KiCad의 'Assign Footprints'를 둘러 보았지만 Molex 5045 헤더(2.5mm 피치)에 딱 맞는 footprint가 보이지 않는다. 피치가 동일한 SPOX 5267을 써도 되는지? 혹은 무난하게 JST의 것을?

펌웨어는 이미 작년에 오랜 기간에 걸쳐 개발과 검증을 거쳤기에 별 걱정은 하지 않는다. 3월 중에 충분히 검토를 거쳐서 JLCPCB에 거버 파일을 보낼 수만 있다면 더 이상 바랄 것이 없겠다.

저자에서 디렉터로 — AI 시대 글쓰기의 변화

• 기획: 정해영(director, 국문으로 바꾼다면 구성 감독, 총괄 설계자, 또는 텍스트 연출자?)
• 텍스트 생성: AI 보조(text produced with AI assistance)

오랫동안 글쓰기는 ‘저자(author)’라는 개념을 중심으로 이해되어 왔다. 저자는 텍스트를 생산하는 사람이며, 글의 의미와 책임의 중심에 있는 존재였다. 책의 표지에는 저자의 이름이 적히고, 학술 논문에서는 저자 순서가 중요한 의미를 가진다. 글은 곧 저자의 창작물이었다.

그러나 디지털 환경과 협업적 지식 생산이 확산되면서 이 전통적인 개념은 조금씩 흔들리기 시작했다. 이미 20세기 후반에 여러 사상가들이 이러한 변화를 지적했다. 예컨대 Roland Barthes는 “저자의 죽음”이라는 유명한 글에서 텍스트의 의미는 저자가 아니라 독자의 해석 속에서 형성된다고 주장했다. 이어 Michel Foucault는 “저자는 하나의 기능(author function)”이라고 말하며, 저자를 절대적 창조자가 아니라 지식 체계 속의 역할로 이해했다.

오늘날 AI 도구가 글쓰기 과정에 깊이 들어오면서 이 변화는 더욱 분명해지고 있다. 이제 많은 글은 한 사람이 처음부터 끝까지 문장을 만들어내는 방식으로 생산되지 않는다. 자료 수집, 초안 작성, 문장 다듬기, 번역, 구조 정리 등 여러 단계에서 다양한 도구와 협업이 개입한다. 때로는 AI가 초안을 만들고 인간이 구조를 수정하며, 다시 AI가 문장을 정제하는 방식으로 글이 완성되기도 한다.

이러한 환경에서는 ‘저자’라는 말이 점점 어색해진다. 글을 직접 타이핑한 사람이 누구인가보다 중요한 것은 글의 방향과 구조를 설계한 사람이 누구인가라는 문제이기 때문이다. 다시 말해 텍스트의 생산 과정에서 중요한 역할은 더 이상 단순한 집필자가 아니라 전체 작업을 기획하고 조율하는 사람에게 있다.

이 역할을 가장 잘 설명하는 말은 아마도 ‘디렉터(director)’일 것이다. 영화에서 감독은 모든 장면을 직접 촬영하지 않는다. 배우가 연기하고 촬영 감독이 카메라를 잡으며 편집자가 영상을 다듬는다. 그러나 영화 전체의 방향과 스타일을 결정하는 사람은 감독이다. AI 시대의 글쓰기도 점점 이와 비슷해지고 있다.

앞으로의 글쓰기에서 중요한 능력은 문장을 얼마나 많이 생산할 수 있는가가 아니라, 어떤 질문을 던지고 어떤 구조를 설계하며 어떤 자료를 결합할 것인가일 가능성이 크다. 글은 점점 더 복합적인 생산 과정의 결과물이 되고, 저자는 그 과정을 지휘하는 역할로 이동한다.

따라서 AI 시대의 글쓰기를 이렇게 표현할 수도 있다.

우리는 더 이상 텍스트의 저자라기보다, 텍스트 생산의 디렉터가 되어가고 있다.

이 변화는 단순히 기술의 문제가 아니라 지식 생산 방식 자체의 변화를 보여준다. 글쓰기는 여전히 인간의 사유에서 출발하지만, 그 사유가 구현되는 방식은 점점 더 협업적이고, 도구 의존적이며, 연출적인 형태로 바뀌고 있다. 저자의 시대가 끝났다고 말하기는 아직 이르다. 그러나 적어도 오늘날의 글쓰기에서 저자의 모습이 과거와 같은 형태로 남아 있지 않다는 것만은 분명해 보인다.

---

이 글은 정해영의 아이디어를 바탕으로 AI(ChatGPT)의 도움을 받아 작성되었습니다.
본 텍스트는 Creative Commons Attribution 4.0 International (CC BY 4.0) 라이선스로 공개됩니다.
출처를 표시하는 조건으로 누구나 자유롭게 이용·수정·재배포할 수 있습니다.
정확성에 대한 보증이나 법적 책임은 제공되지 않습니다.

[DokuWiki] 문서 폭을 좁게 만드는 TOC, 어떻게 할 것인가?

DokuWiki에서는 문서 안에 자동으로 TOC(table of contents, 목차)를 만들어 준다. TOC는 문서의 내용을 신속하게 파악하고 특정 위치로 빨리 이동하는 데 큰 도움을 준다.

요즘은 ChatGPT를 써서 마크다운 문서를 만든 뒤 Commonmark Plugin을 이용해 DokuWiki에 삽입하는 일이 많다. 마크다운 문서는 GitHub에 올리기 좋고, 웹브라우저에서도 쉽게 열 수 있기 때문이다. DokuWiki에서는 새 문서를 <!DOCTYPE markdown>이라는 줄로 시작한 다음, 마크다운 본문을 복사해 넣으면 된다.

그런데 이렇게 만들어진 문서에서는 TOC가 끝나고 나서야 비로소 본문이 시작된다. 그래서 위쪽에 긴 여백이 생겨 보기가 매우 좋지 않다. 왜 그럴까? Commonmark Plugin의 렌더링 방식 차이 때문이다. DokuWiki 문법으로 작성된 문서는 본문이 먼저 시작되고, TOC는 오른쪽에 float되며, 본문은 그 옆으로 자연스럽게 흐른다. 그러나 내가 사용한 Markdown wrapper div는 CSS 문제로 인해 본문이 아래로 밀려 내려가면서 공백이 크게 생기는 것이다.

다음은 너무 긴 여백이 보기 흉해서 그림을 삽입한 예이다. 하지만 TOC가 너무 길어지면 그림을 넣어도 별 소용이 없다.

글 원본 링크는 여기. ChatGPT가 당당하게 자기를 '저자'라고 표현하였다.

conf/userstyle.css에서 TOC가 나오지 않게 하면 어떨까? 하지만 이 방법은 위키 사이트 안의 모든 문서에서 TOC가 표시되지 않게 만들기 때문에 바람직한 해결책이 아니다. TOC를 표시하지 않을 문서를 일일이 CSS에 나열하거나, 네임스페이스 단위로 따로 설정할 수도 있겠지만, 그것 역시 번거로운 일이다.

문서마다 개별적으로 자동 TOC를 나오게 하거나 혹은 나오지 않게 하면 가장 좋겠지만, 즉 문서 상단에 위키 매크로인 ~~NOTOC~~를 삽입하면 좋겠지만, 현재 내가 쓰는 플러그인에서는 이것도 잘 먹지 않는다.

DokuWiki 안에서 Markdown을 쓰는 순간 위키 기능의 절반을 잃는다!

적어도 구조화된 기술 문서를 위키 안에서 안정적으로 운영하려면, Markdown보다는 처음부터 DokuWiki 문법으로 작성하는 편이 낫겠다. GitHub와의 호환성은 조금 아쉽더라도, 위키 본연의 기능을 온전히 살리는 쪽이 더 중요해 보인다.

오늘 이 문제를 해결해 보고자 ChatGPT와 더불어 여러 시도를 해 보았으나, 결국은 ‘futile cycle’만 돌고 말았다. 인공지능에 약간 실망하게 된 하루였다.