개념을 설명하는 글쓰기 경험 회고하기
처음 지금 다니고 있는 회사에 입사했을 때, 제 주된 업무는 기술 개념서를 작성하는 일이었습니다. 지금은 전략 업무를 맡고 있어 이 일을 지금도 하고 있지는 않지만, 돌아보면 그 시기에 제가 만들었던 문서들이 나름 의미있는 결과물 중 하나였다고 생각합니다. (솔직히 말하자면 그 시절의 업무에 더 집중하고 싶다는 마음이 아직도 제 안 어딘가에 남아있기도 해요😉) 한동안 구성원을 위한 기술 개념서를 쓰는 일을 맡았고 그 과정에서 기술을 설명하는 글쓰기는 개념을 설계하는 일이라고 생각했습니다.
개념을 설계하는 일?
제가 쓴 문서는 사용자 매뉴얼도 아니고, 대외 홍보용 화이트페이퍼도 아니었습니다. 내부적으로는 ‘기술백서’라고 불렀지만 여기서는 조금 더 정확하게 이렇게 설명하면 이해가 쉬울 것 같네요.
“새로 입사한 동료나, 기술을 이해하고자 하는 임직원을 위한 개념 중심의 내부 콘텐츠”
그 시기 우리 조직은 새로운 기술을 다수 도입하고 소개하던 단계였고, 그 흐름 속에서 기술의 핵심 개념을 정리해서 전달하는 역할이 필요했기에 이런 업무를 수행했습니다.
매뉴얼과는 다른 글쓰기
그 전까지는 저는 매뉴얼 중심의 문서를 써왔기 때문에 이런 개념서 작업은 처음이었습니다. 특히 어려웠던 점은 ‘무엇을’ 보다 ‘어떻게’ 말할 것인가였습니다. 기술을 정의하려고 들면 세부 정보에 매몰되기 쉽고, 반대로 너무 얕게 다루면 인터넷 검색보다 못한 결과물이 되기 십상이죠.
그래서 저는 정보를 나열하더라도 독자의 이해 흐름에 맞게 설계해보고자 했습니다.!
내가 세운 작성 기준 3가지
- 맥락부터 제시한다
‘이 기술이 왜 필요한가’를 앞부분에 설명했습니다. 기술의 도입 배경이나 해결하고자 하는 문제를 제시하면 왜 우리가 이 기술을 소개하려고 하는지 쉽게 내용을 받아들일 수 있다고 생각했습니다.
기술백서라는 키워드로 찾다보니 ‘삼성SDS 클라우드 기술백서’도 참고했었는데요 문서의 대부분이 이런 구조를 따르고 있는 것 같습니다. 문제인식→원인분석→ 해결책 제시. 이렇게 기능이나 기술을 설명하기 전에 왜 이 기능/기술이 필요한가 순으로 전개하면 도입부분을 어렵지 않게 작성할 수 있었습니다. (삼성 SDS 클라우드 기술백서) - 문서가 길면 요약을 작성하자
긴 문서에는 도입부에 간결한 요약을 넣어 전체 구조를 파악할 수 있도록 했습니다. 요약은 문장형태로 설명할 수도 있겠고, 항목별로 작성하는 방법도 있습니다. 하나의 예시로 ‘우리 조직에 마이크로서비스 아키텍처를 왜 도입하는가?’ 라는 게시글을 조직 위키에 작성한다고 가정하면 문장형 요약에서는 주로 아래와 같은 형태로 작성해왔습니다.
[주제 등장 배경 및 목적]. 이 문서는 [핵심 개념과 적용 목적]을 정리하며, [도입/활용 시 주요 고려사항]을 함께 다룹니다. 이런 형태를 적용하면
“ 우리 조직은 기존의 모놀리식 구조로 인해, 작은 기능 수정에도 전체 서비스를 재배포해야 하는 비효율과, 신규 기능 도입 시 높은 운영 리스크라는 문제를 반복적으로 겪어왔습니다.이러한 구조적 한계를 극복하고자 마이크로서비스 아키텍처(MSA)의 도입을 검토하게 되었고, 이 문서는 그 도입 목적과 개념, 그리고 실제 적용 시 고려해야 할 주요 사항들을 정리한 내용입니다."
이걸 항목별로 작성한다면 목적/개념/도입효과 처럼 카테고리를 나눠서, 각 항목마다 핵심 내용을 요약해 볼 수 있습니다. 읽는 흐름이 중요한 문서라면 문장형으로 시작해서 풀어가고, 빠르게 핵심을 파악하고 검색/탐색이 중요한 문서라면 항목별로 작성하는 게 좋을 듯합니다. - 쉽게 이해할 수 있게
가능한 간결한 언어를 사용하고 적절한 시각자료가 있다면 적극적으로 활용했습니다. 개인적으로는 노션 가이드 문서가 쉽고 예시와 시각자료가 적절하게 들어가있다고 생각합니다. (Notion 공식 가이드) 각 단계마다 스크린샷을 첨부하고, 실제 사용자가 물어볼 법 한 예시를 통해서 설명해 주는 게 좋았습니다.
추가로 노션 가이드 문서에서도 위 두 가지 방식처럼 작성한 예시가 있어서 가져와봤습니다. ‘언제 레이아웃 기능이 필요한가’ → ‘레이아웃을 사용하면 해결할 수 있는 것’을 보여준 다음 본문에서 다루는 내용의 요약까지 작성되어 있네요.
언젠가 이런 가이드 문서를 만들게 되면 노션 가이드문서를 참고하게 되지 않을까 싶습니다.
(다른 테크니컬라이터분들은 노션의 가이드 문서를 보고 어떻게 생각하는지도 궁금하네요🤔)
글을 읽게 만들기 위한 부가작업
추가로 신경 썼던 건 좋은 내용을 잘 쓰는 것 보다도 어떻게 하면 더 많은 사람들이 이 글을 읽게 만들 수 있을까였습니다. 정말 공들여 쓴 글을 아무도 보지 않는다면 괜히 슬프잖아요😥
그래서 웹사이트처럼 꾸밀 수 없는 사내 시스템 환경에서도 가독성을 최대한 높이기 위해 게시글의 HTML을 아주 미약하게라도 수정해 가며 편집했고, 썸네일이 붙는 포맷으로 바꾸고 통일감 있게 디자인했습니다. 사내 메인 페이지에 노출 요청도 했고 실제로 더 많은 사람들이 더 쉽게 접할 수 있게 되었습니다.(아쉽게도 지금은 메인페이지 리뉴얼로 더 이상 노출되진 않지만요..!)
그래서 내가 배운 건
어쩌다 보니 단기 프로젝트처럼 진행되었지만 이 경험은 제게 이후 전략 업무에서 기술 개념을 정리하는 장표나 보고서를 만들 때 많은 도움이 되었다고 생각합니다. 제가 입사한 지 얼마 안 되었을 때 기술에 대한 이해도를 높이는 데도 많은 도움이 되었고, 무엇보다 복잡한 개념을 어떻게 명료하게 설명할 것인가를 고민해 보는 기회가 되었던 것 같습니다.✍️