수상 경력의 devportal은 말 그 이상이다

Source: Dev.to

“개발자 콘텐츠 책임자로서 3년을 되돌아보며.”

Viam 문서는 복잡하고 방대한 개발자 플랫폼, 여러 언어로 제공되는 SDK, 그리고 스타트업처럼 빠르게 변화하는 API를 다룹니다. 이러한 이유로 문서는 여러 상을 수상했습니다.

하지만 어디서 시작했을까요? 이 Web Archive capture는 제가 시작하기 전, 3년 전의 모습을 보여줍니다.

우리 팀은 바로 작업에 착수했고, 그 겸손한 시작점으로부터 1년이 지나면서 문서는 읽을 가치가 있는 형태로 변모했습니다. 우리는 Devportal Awards에서 Best Overall SME Devportal 상을 포함한 여러 상을 수상했으며, 자세한 내용은 LinkedIn post를 참고하세요. 우리는 올바른 방향으로 나아가고 있었습니다.

문서 사이트 개선하기

좋은 문서 포털은 단순히 기술 문서만을 의미하지 않습니다; 사용자가 매일 상호작용하는 웹사이트이기도 합니다. 이를 염두에 두고 여러 사용성 기능을 추가했습니다.

• 변경 로그 항목, 튜토리얼, 모듈(제품 출시 이전부터) 필터링을 위한 동적 요소
  Typesense(오픈소스 검색 엔진)와 Algolia의 InstantSearch.js(오픈소스 UI 라이브러리)를 조합해 정적 사이트에 이러한 컴포넌트를 추가했습니다.

• 호버 시 추가 정보를 보여주는 인‑텍스트 용어집 항목
  Hugo는 전체 프론트엔드 프레임워크 없이도 커스터마이징이 가능한 멋진 문서 사이트 프레임워크입니다. 저는 Kubernetes 작성자들이 만든 Hugo 기반 작업을 활용했습니다.

• 기능 및 하드웨어 동작을 보여주는 GIF
  하드웨어 작동은 시각적으로 전달되는 것이 가장 효과적이므로, 초기부터 이미지를 활용해 제품을 살아있게 보여주기로 했습니다. Hugo에서 짧은 코드를 추가해 GIF를 대역폭 친화적인 비디오 형태로 제공했으며, SEO 규칙을 강제 적용하기 위해 Hugo를 광범위하게 사용했습니다.

GitHub Actions를 활용한 자동화

복잡한 플랫폼의 문서 영역을 최신 상태로 유지하면서 사용자용 웹 애플리케이션도 관리하는 일은 작은 팀에게 결코 쉬운 일이 아닙니다. 우리는 주로 GitHub Actions를 통해 자동화에 크게 의존했습니다:

• Vale를 이용한 스타일 가이드 검사 – prose(문장) 전용 린터입니다. 스타일 가이드 규칙을 포괄하는 정규식을 만든 뒤, Vale가 자동으로 위반 사항을 표시합니다. 저는 MongoDB에서 Vale를 처음 발견했고, 현재도 사용 중인 규칙들을 작성했습니다(my Vale repo; 이후 커뮤니티에서 mongodb‑vale‑action으로 공개되었습니다).

• 코드 샘플 테스트 – 프로젝트 설정/해제와 각 샘플을 구분하는 마크업을 포함한 파일에 코드 샘플을 배치하는 테스트 스위트를 구축했습니다. GitHub Actions와 Bash 스크립트가 테스트를 실행하고 마크업으로부터 최종 샘플을 생성합니다. 초기 작업이 큰 효과를 발휘했습니다: 엔드‑투‑엔드 테스트가 API 변경 및 장애를 포착해, 배포된 코드에 대한 신뢰를 높여줍니다.

• 죽은 링크 감지 및 포워딩 – htmltest는 깨진 링크 감지에 뛰어나지만, 이동된 링크를 처리하려면 추가 작업이 필요했습니다. 저는 Netlify 통합(“No more 404s” 플러그인)으로 이를 해결했습니다. Netlify는 HTML 수준 리다이렉트에서 올바른 HTTP 수준 포워딩으로 전환하는 데에도 도움을 주었습니다.

Generative AI

우리는 생성형 AI를 활용한 실험을 많이 진행했습니다. PR에서 얻은 정보를 기반으로 문서를 자동으로 업데이트하는 개념 증명 도구를 만들었고, 이후 이보다 더 뛰어난 기능을 제공하는 업체를 발견했습니다. AI가 생성한 콘텐츠는 여전히 철저한 검토가 필요하지만, 앞으로의 가능성이 큰 방향이라고 생각합니다. AI 채팅 모델은 훨씬 더 발전했으며, 신중하게 사용할 경우 얼마나 유용한지에 놀랐습니다.

Fact‑Checking에서의 등장
생성형 AI의 결과물을 일종의 다른 형태의 검색으로 바라보면, 비판적 검토가 필요하다는 점을 항상 강조할 수 있다고 생각합니다. 업계 전체적으로 생성형 AI가 어떻게 작동하는지에 대한 사용자 리터러시를 향상시킬 과제가 남아 있습니다—사용자들은 AI가 갖지 못한 기능을 기대하거나, 비밀번호와 같은 비밀 정보를 AI 채팅에 맡기는 경우가 너무 흔합니다.

우리의 AI 활용 경험에서 얻은 교훈은 여러 블로그 포스트에 담을 수 있을 정도이지만, 여기서는 간략히 정리합니다: 사전 구축된 임베드 가능한 AI‑채팅 툴을 찾고 있다면 Inkeep 을 추천합니다.

단일 진실의 원천: SDK 문서와 “메인” 문서

우리는 자동 문서 생성을 활용해 작업량을 줄였습니다. 예를 들어, SDK 문서에서 메인 플랫폼 문서를 자동으로 생성했습니다. SDK 문서와 메인 문서 사이에서 코드 샘플을 오가며 복사하는 경우가 많아진 것을 깨닫고, 단일 진실의 원천을 만들기 위해 노력했습니다.

• 코드 샘플의 위치: 개별 API 함수를 사용하는 방법을 보여주는 샘플은 SDK에 포함시켜야 합니다.
• 달성 방법: SDK 문서는 SDK 코드에 있는 docstring에서 자동으로 생성되므로, 문서가 코드와 함께 위치해 최신 상태를 유지할 가능성이 높아집니다.
• 워크플로우: SDK 문서를 받아 메인 문서의 일부를 자동으로 생성하는 시스템을 구축했습니다. 시스템이 실행되는 동안 새로운 변경 사항을 확인하고 검토하며, 필요할 경우 SDK 문서를 수정했습니다.

그 결과 일관성이 향상되고 수작업이 크게 줄어들었습니다.

결론

문서가 제가 작업한 유일한 것이 아니었지만, 그것이 제가 가장 자랑스러워하는 작업입니다. 3년이 지난 지금, 문서를 인계하면서 아직 해야 할 일이 남아 있지만—우리가 이룬 것에 만족합니다.

직접 확인해 보세요: