Technical Writing

C4 모델과 C4-PlantUML을 이용한 소프트웨어 구조 다이어그램 만들기

이번 글에선 Write the Docs Portland 2020 온라인 발표 중 하나를 소개하고 이 내용에 대해 이야기해볼까 합니다.

소프트웨어 구조를 파악할 때 글보다는 소프트웨어 구조 다이어그램과 같은 그림을 통해 훨씬 빠르게 이해한 경험이 많으실 겁니다. 그런데 소프트웨어 구조 다이어그램 작성에 익숙하지 않다면 막상 그리려고 해도 그리는 게 쉽지 않습니다. 어떤 도구를 써서 어떻게 시작해야 할지도 고민되고 그리기 시작한 뒤에도 이렇게 그리는 게 맞는지 자문할 때가 많으셨을 겁니다.

이번 글에서 소개할 발표는 Avi Flax 님의 Set your data free with model-based architecture diagramming 세션으로, 저와 여러분의 고민을 조금이나마 해소할 수 있을 것 같아 공유하려고 합니다.

그것이 알고 싶다 – 왜 개발자는 글을 못 쓸까?

개발자는 글을 못 쓰는 것일까? 아니, 개발자는 글을 안 쓰는 것일까? 아니, 개발자는 글을 쓰기 싫은 것일까?

저는 현직 테크니컬 라이터이자 전직 개발자로서 현장에서 겪은 경험을 바탕으로 이 현상을 심층 분석해 보려고 합니다. 단, 분석만입니다. 마치 매년 12월~1월에 서점에서 만나볼 수 있는 다양한 자기 계발서 마냥 상당히 이론적인 내용을 나눕니다. 누군가에겐 매우 따분한 이야기가 될 수 있겠지요. 누구나 머리로는 알고 있는 내용이지만 실천으로 이어질 가능성이 현저히 낮은 내용 말입니다.

주석 분석기를 이용한 간단한 API 문서화 방법

테크니컬 라이터로서 가장 재미있는 순간은 바로 새로운 프로젝트를 시작할 때입니다. 프로젝트를 시작하는 순간에는 모든 것이 열려 있어 자유로우며, 그 자유가 새로운 도메인에 대한 탐구심을 자극하기 때문입니다. 그런 점에서 짧지만 굵게 새로운 것을 시도하고 배울 수 있는 기술 문서 컨설팅은 제게 참 신나는 업무입니다. 이번 글에서는 몇 달 전에 진행했던 API 문서화 컨설팅에서 배운 내용을 공유하려 합니다. 주제는 새로운 언어를 위한 소스 코드 주석 기반 API 문서화 도구 만들기입니다. 정확히 말하면 ‘도구 만들기’라기보다 ‘도구 찾아 적용하기’이므로, 코딩이 많이 필요할 거라는 기대 혹은 염려는 가슴 한편에 고이 접어둬도 좋습니다.

테크니컬 라이팅 컨퍼런스: API the Docs Chicago 2019 방문기

미국에는 머스타드 박물관이 있다고 합니다. 무려 머스타드를 위한 박물관도 있는데! ‘헨리 밀러’나 ‘어니스트 헤밍웨이’ 등 훌륭한 작가와 오랜 세월 전세계적으로 사랑받고 있는 작품을 쏟아낸 나라에 작가를 위한 박물관이 없다는 사실에 개탄을 금치 못한 사람들이 의기투합하여 2009년 재단을 설립하고 2017년, American Writers Museum(AWM)을 탄생시켰습니다. 그리고 바로 이 AWM이 위치한 시카고에서 API the Docs Chicago 컨퍼런스가 개최되었습니다. 그러고 보니 어니스트 헤밍웨이도 시카고 출신이네요(시카고 여행지 추천 목록에 헤밍웨이 생가가 있다는 사실!). 그동안 유럽에서만 개최되어 온 API the Docs가 처음으로 미국에서 개최된 것도 뜻깊은데 장소까지 테크니컬 ‘라이터’에게 의미있는 장소였던 이번 API the Docs Chicago에 참석하게 된 후기를 늦게나마 여러분과 나누고자 합니다.


문서 엔지니어링과 API 문서화

테크니컬 라이터(technical writer)라는 말을 들으면 대부분 ‘라이터’라는 단어만 보고 ‘글 쓰는 사람’이라 생각하기 십상입니다. 물론 틀린 것은 아니지만, 실상 키보드를 두드리며 글 쓰는 일이 테크니컬 라이터 업무의 대부분을 차지하지는 않습니다. 하루에 얼마 동안 글을 쓰는지 측정해 본 적은 없으나, 테크니컬 라이터 톰 존슨(Tom Johnson)이 말하기로는 일하는 시간의 약 10%라고 합니다.

그렇다면 그 밖의 시간에는 뭘 할까요? 역시 톰 존슨에 따르면 개발자 인터뷰, 다른 사람이 쓴 문서 리뷰, 앱 스크린 캐스팅이 필요할 때 아이폰 탈옥, 미디어위키에서 링크된 이미지에 캡션 넣는 방법 찾기 등등이라고 합니다. 그중에서도 제가 말하고자 하는 일은 비록 ‘아이폰 탈옥’ 같은 건 아니지만 결과적으로는 글쓰기와는 전혀 관계 없어 보이는 엔지니어링에 관한 것입니다.

Technical Communication Symposium 2018 참석기 – 기술 문서의 번역 품질 평가 방법

안녕하세요. LINE GAME PLATFORM의 문서 제작과 배포를 담당하는 테크니컬 라이터 김지현입니다. LINE GAME PLATFORM은 한국과 일본, 두 거점에서 기획하고 개발하는 프로젝트인데요. 이에 맞춰 문서도 한국어와 일본어, 두 가지 언어로 작성하고 있습니다. 두 가지 언어로 글을 쓸 때 가장 어려운 점은 언어별로 독자의 지역적, 문화적 배경을 글에 녹여내야 한다는 것입니다. 저는 일본어로 글을 쓰는 게 어렵지는 않지만 모국어가 한국어고 […]

테크니컬 라이팅 컨퍼런스: Write the Docs Prague 2018 방문기

안녕하세요. Clova 기술 문서 작성 및 관리 업무를 맡고 있는 Technical Writing 팀 강정일입니다.

Write the Docs(이하 WTD)는 커뮤니케이션, 문서, 그리고 사용자를 연구한 경험을 서로 공유하는 커뮤니티입니다. WTD는 특히 소프트웨어 산업과 관련된 분야에 좀 더 집중하고 있습니다. 이 커뮤니티는 매년 정기적으로 봄에는 미국 포틀랜드에서, 가을에는 체코 프라하에서 WTD 컨퍼런스를 열고 있는데요. WTD 컨퍼런스에서 참석자들은 각자가 문서 및 프로젝트를 관리하면서 얻은 경험을 공유하고, 좀 더 관심있는 주제가 있으면 토론도 하면서 새로운 사람과 뉴스를 접할 수 있는 기회를 가집니다.

이번 글에서는 제가 들었던 세션 중 가장 기억에 남는 두 세션과 각 세션에 대한 제 소감을 공유해드리려고 합니다.


API the Docs 참관 후기

안녕하세요? 테크니컬 라이터 Serizawa입니다. LINE은 개발자들이 최신 기술 동향을 파악할 수 있도록 해외 컨퍼런스 참가를 지원합니다. 이번 포스팅에서는 제가 이 지원 제도를 이용해 다녀온 API 문서화 관련 컨퍼런스인 API the Docs에 대해 전해 드릴까 합니다.

API the Docs는 테크니컬 라이터, API 개발자, 프로덕트 오너, 에반젤리스트를 대상으로 한 API 문서화에 특화된 행사로, 해마다 여러 차례, 세계 각지에서 열립니다. 개발 경험(Developer eXperience, 이하 ‘DX’)의 중요 요소인 문서화에 관해서 최신 우수 사례나 경향 등을 공유하고 의견을 나누는 자리이지요.

LINE 개발자 사이트 개편 – 비하인드 스토리

안녕하세요, 저는 LINE의 서비스 제품에 대한 기술 문서를 담당하는 테크니컬 라이터, 케네스 라우(Kenneth Lau)입니다. 아마 이미 아시는 분들도 계시겠지만, 저희는 최근에 LINE 개발자 사이트를 개편하였습니다. LINE 개발자 사이트는 LINE Login이나 메시지 API 등 LINE이 제공하는 서비스에 대한 정보와, 여러분의 앱을 관리할 수 있는 개발자 콘솔을 제공합니다. 무엇을 개편하였는지 간략하게 소개하는 글을 준비하였으니 궁금하신 분들은 확인해 보세요.

저는 이번 글을 통해서 개발자 사이트 개편에 따른 기술적 변화와, 기술 문서를 작성하는 과정에 대해 다루고자 합니다. Static site generator를 도입한 과정과 이로 인해 문서화에 생긴 변화와 앞으로 저희가 어떤 계획을 가지고 있는지에 대해 말씀드리겠습니다. 그 전에, 우선 개발자 사이트에 대해서 간략하게 소개 드리겠습니다.