안녕하세요. 인포그랩 프로덕트 팀에서 백엔드 엔지니어로 근무하는 Andy입니다. 엔지니어는 README, API 설계 문서, 가이드, 기술 블로그 등 다양한 기술 문서를 작성합니다. 오늘은 이 중에서도 기술 블로그 작성법을 이야기하고자 하는데요. 기술 블로그는 기술 지식과 정보를 스토리텔링 하듯 아티클 형태로 전달하죠. 이는 개조식으로 쓰는 보고서와 다르고, 분량이 길어 작성하기 쉽지만 않습니다. 특히 사내 기술 블로그는 기업 공식 채널인 만큼 콘텐츠 완성도에 신경이 쓰이고요.
이에 기술 블로그 작성을 부담스러워하는 엔지니어도 많은데요. 엔지니어는 글쓰기가 본업이 아니기에 기술 블로그를 잘 써야 할 동기를 부여받거나, 글을 능숙하게 작성하기가 어려울 수 있습니다. 아울러 대내외 프로젝트, 고객사 기술 지원과 교육, 개발 등 본업을 수행하면서 사내 기술 블로그 작성까지 요청받으면 마감일 안에 글을 완성하기 벅찰 수 있죠. 또 콘텐츠 품질까지 높이려면 부담이 더 커져서 기술 블로그 작성을 시작조차 하기 힘들 수 있습니다.
요즘은 생성형 인공지능(AI) 기술로 콘텐츠 제작 문턱이 낮아졌습니다. 그러나 여러 가지 이유로 자기가 직접 기술 블로그를 써야 하는 이들도 있는데요. 이 글에서는 인포그랩과 저의 기술 블로그 업무 수행 방식을 토대로 ‘엔지니어가 마감일 안에 사내 기술 블로그를 쉽고 빠르게 고품질로 완성 하는 팁’을 공유하고자 합니다.
인포그랩의 기술 블로그 운영 방식
인포그랩은 매주 수요일마다 기술 블로그에 신규 콘텐츠를 발행합니다. 발행일이 공휴일과 겹치면 일정을 하루 앞당길 때도 있죠. 이와 별개로 GitLab 릴리즈 노트와 보안 릴리즈 소식은 GitLab 공식 발표가 나온 다음 날 바로 발행합니다.
인포그랩은 기술 블로그에 콘텐츠를 정기 발행하기 위해 당번과 마감일을 정해 운영합니다. 당번은 마감일과 발행일을 지키기 위해 책임감 있게 기술 블로그를 작성하는데요. 기술 블로그 마감, 배포 일정을 정례화한 뒤로 그 누구도 발행일을 지키지 못한 적은 단 한 번도 없습니다.
인포그랩 기술 블로그에는 내부 DevOps 엔지니어, 소프트웨어 엔지니어, 프로젝트 매니저, 세일즈 매니저, 전략 & 경영지원 매니저, 테크니컬 라이터 등 다양한 직무의 구성원이 글을 씁니다. 저자별로 직무와 특성이 다채롭다 보니 DevOps, 개발, DevRel, 테크니컬 라이팅 등 기술을 중심으로 여러 주제의 콘텐츠를 선보입니다.
Andy의 기술 블로그 업무 수행 방식
저는 두 달에 한 번꼴로 사내 기술 블로그에 글을 기고합니다. 올해 초 인포그랩에 입사해 지금까지 총 3편의 기술 블로그를 작성했는데요. OKR, 기술 부채, 기술 블로그 작성법을 주제로 글을 썼습니다. 이중 ‘기술 부채 어떻게 상환할까?’라는 글은 개발자 커뮤니티 ‘커리어리’에 소개되기도 했습니다.
저는 기술 블로그를 작성할 때 개인적으로 흥미 있으면서 기술 커뮤니티에도 유의미한 주제를 선정합니다. 그다음, 개요를 작성하고, 자료를 조사하고요. 이어서 초안을 쓰고, 막히는 점이 있으면 사내 테크니컬 라이팅 시스템을 활용해 문제를 해결합니다. 초안을 작성한 뒤에는 AI로 글 리뷰를 받고요. 글을 개선해 마감일까지 사내 테크니컬 라이터에게 제출합니다. 이후 사내 테크니컬 라이팅 시스템에 따라 리뷰, 편집이 이뤄져 발행일에 글이 배포되죠.
개발 업무를 수행하면서 마감일에 맞춰 격월로 기술 블로그를 작성하는 일은 녹록지만 않은데요. 저는 업무 계획을 체계적으로 수립해 시간을 효율적으로 관리하고, 자료를 미리 조사하며 기한 안에 내실 있는 글을 완성하려 노력합니다. 다행히 지금까지 마감일을 어긴 적은 단 한 번도 없는데요. 제가 시간·업무·심적 압박을 관리하며 주어진 시간에 기술 블로그를 양질의 콘텐츠로 완성하는 방법을 프로세스별로 소개하겠습니다.
1. 주제 선정
저는 다음 기준에 따라 기술 블로그 주제를 선정합니다. 첫째, ‘평소에 내가 고민하거나 알고 싶고, 독자에게도 흥미로운 주제인가?’. 둘째, ‘내가 이미 알고 있는 지식인가?’입니다. 제가 관심 없고, 재미를 못 느끼는 주제로 글을 쓰려면 시간과 에너지가 낭비되는데요. 개인적인 욕구도 함께 충족하는 주제를 선정하면 동기 부여를 받아 의욕적으로 글을 작성할 수 있습니다.
지난 6월 제가 쓴 "기술 부채 어떻게 상환할까?"라는 글이 그 예인데요. 그때 저는 클린 코드와 팀 기술 부채 해결 방안에 관심이 많았습니다. ‘기술 부채’를 주제로 글을 작성하면 제 호기심과 궁금증을 해결하고, 글도 즐겁게 쓸 수 있을 거로 기대했는데요. 이러한 이유로 해당 주제를 선정했고, 글을 준비하며 많은 걸 배웠습니다.
2. 개요 작성
주제를 선정하면 대략 개요를 작성합니다. 여기서 중요한 점은 ‘어떤 자료를 조사하면 좋을지’, ‘글의 방향성이 일관되는지’ 생각하며 개요를 짜야 한다는 점입니다. 이는 자료 조사 시간을 절약하고, 글을 통일된 흐름으로 작성하는 데 도움이 됩니다.
- 서론
- 대부분의 회사는 기술 부채를 가지고 있다.
- 기술 부채는 나쁜 것인가?
- 그렇지 않다. 기술 부채는 성장에 따라 자연스럽게 생기는 것이다.
- 본론
- 기술 부채란 무엇인가?
- 기술 부채의 유형에는 어떤 것이 있는가?
- 기술 부채 유형별 예시로 무엇이 있을까?
- 기술 부채를 해결하기 위해 어떤 노력이 필요한가?
- 기술 부채 유형별로 취할 수 있는 액션 포인트는 무엇인가?
- 인포그랩에서는 기술 부채를 어떻게 해결하고 있는가?
- 팀 내부에서 수행하는 일을 잘 정리해서 설명 필요
- 마무리
- 요약, 맺음말
저는 "기술 부채 어떻게 상환할까?"라는 글을 쓸 때, 위와 같이 개요를 정리했는데요. 개요를 보면, ‘대략 어떤 키워드로 자료를 조사할지’ 방향이 잡힙니다. 저는 개요를 참고해 아래 세 가지 사항을 조사하기로 했습니다.
- 기술 부채 이론: 개념, 유형, 예시
- 기술 부채 해결 방법: 모범 관행
- 인포그랩의 기술 부채 해결 노력: 사례
개요에서 키워드를 도출해 자료 조사 방향을 설정하니, 조사 시간을 효율적으로 사용할 수 있었습니다.
3. 자료 조사
개요를 작성한 뒤, 본격적으로 자료를 조사합니다. 기술 블로그 주제에 따라 내부 자료 를 참고해야 할 수도 있는데요. 개요가 있으면, ‘어떤 내부 자료가 필요한지’ 미리 판단할 수 있고요. 상급자에게 해당 자료의 활용 가능 여부를 빨리 타진하고, 일찍 검토받을 수 있습니다. 이로써 내부 자료 활용 여부를 신속히 승인받을 수 있고요. 자료 수집 시간도 단축할 수 있죠. 이는 내부 자료가 아닌 외부 자료를 조사할 때도 비슷합니다.
4. 초안 작성
자료 조사를 마치면 초안을 씁니다. 초안을 작성하다 보면 여러 문제점을 발견할 수 있습니다. 글 내용이 모자랄 수도 있고요. 글 방향이 잘못될 수도 있습니다. 스스로 글솜씨가 부족하다고 느낄 수도 있죠. 본업도 빡빡한데 ‘한정된 시간에 고품질 콘텐츠를 완성해야 한다’는 부담까지 겹치면 막막하기도 합니다.
이때 저는 사내 테크니컬 라이터의 조언을 최대한 활용합니다. ‘혼자 고민하느라 많은 시간을 흘려보내기보다 동료 도움을 받아 빠르게 문제를 해결하는 게 더 낫다’고 보기 때문입니다. 테크니컬 라이터에게 문제를 이야기하면, 상세한 조언을 받아 글을 더 나은 방향으로 개선할 수 있습니다.
5. AI 리뷰
초안을 작성한 뒤, AI의 피드백을 받습니다. 저는 ChatGPT를 활용하는데요. AI에 다음 기준으로 피드백을 요청합니다.
- 중복 표현과 오타가 있는지
- 글이 매끄러운지
- 글에 부족한 내용과 추가할 내 용이 있는지
AI를 리뷰에 활용하면 내 글을 객관적으로 판단하고, 사람이 보지 못한 허점을 발견하는 데 도움이 됩니다. 사내에 글을 리뷰할 사람이 없다면, AI 리뷰어가 요긴할 수 있고요. AI에 쓸 수 있는 기술 블로그 리뷰 프롬프트가 궁금하신 분은 인포그랩 기술 블로그의 “테크니컬 라이팅에 프롬프트 엔지니어링 활용하기” 글을 참고하세요.
6. 제출
위 과정을 거쳐 글을 개선한 다음, 마감일 안에 사내 테크니컬 라이터에게 최종 리뷰를 요청합니다. 사내 테크니컬 라이팅 시스템에 따라 모든 리뷰와 편집이 완료되면 발행일에 글이 배포되죠. 인포그랩은 기술 블로그를 배포할 때, 슬랙과 상호작용을 하는 백엔드 애플리케이션인 슬랙봇도 활용합니다. 자세한 내용은 인포그랩 기술 블로그의 “슬랙봇을 활용한 기술 블로그 배포 자동화 이야기” 글에서 확인하세요.
기술 블로그 업무 임하는 마음가짐
저는 기술 블로그 업무를 수행할 때 “이것만큼은 놓치지 말자”라고 지키는 철칙이 있습니다.
-
마감일 엄수 - 내 전문 분야가 아니라도 전문가처럼 업무 처리하기
어떤 업무든 마감일을 지키는 건 당연합니다. 그러나 엔지니어 본업이 너무 바빠서 시간 여유가 없을 때 "나는 엔지니어니까 글 쓰는 게 늦어져도 괜찮겠지"라고 생각할 수도 있습니다. 이러한 마음가짐을 경계하고, “전문가가 아니더라도 할당된 업무는 ‘전문가처럼’ 처리하자”라고 생각합니다. 그러면 글을 더 빠르게 마무리하고 본업에 집중할 수 있습니다. 이 글도 약속한 일정보다 일주일 앞서 마감했습니다.
-
예상치 못한 일정 고려 - 미리 자료 조사하고 메모하기
이는 ‘마감일 엄수’와 연결되는 내용입니다. 개발 업무를 수행할 때, 계획한 업무 외에 다른 업무가 생겨 일정이 빡빡해진 일을 경험하셨을 겁니다. 또 기존 개발 건이 커져서 더 많은 리소스가 필요해질 때도 있고요. 이때 기술 블로그 작성을 미루면 결국 마감일이 임박했을 때, 급하게 작업해 글을 저품질로 작성할 가능성도 있습니다. 최악의 경우, 마감일을 못 지킬 수도 있죠.
이러한 불상사를 방지하기 위해 저는 미리 세운 개요를 토대로, 글에 활용할 자료를 틈틈이 조사합니다. 아울러 노션 페이지에 참고 자료 링크와 각각 링크의 활용법을 메모하죠. 이 메모를 활용하면 초안을 빠르게 작성할 수 있습니다. 나아가 예상치 못한 업무가 생겨도 마감일 안에 글을 완성할 수 있고요. 글을 보완할 시간이 확보되니 글 완성도를 높이는 데 도움이 됩니다.
맺음말
저는 양질의 글을 작성하되, 최소한의 시간을 투자하도록 기술 블로그 업무를 전략적으로 수행합니다. 이 글에서 다룬 제 핵심 전략은 다음과 같은데요.
- 구체적 개요 작성: 글의 방향성과 자료 조사 포인트를 확인하며 개요를 상세히 짭니다. 이로써 자료 조사 시간을 줄이고, 글을 일관된 흐름으로 작성할 수 있습니다.
- 동료 적극 활용: 초안을 쓰다 막히면 동료 도움을 적극적으로 받습니다. 특히 사내 테크니컬 라이터의 조언을 받아 글을 개선합니다.
- AI로 리뷰 효율화: 초안을 완성하면 AI의 피드백을 받습니다. 중복 표현과 오타를 검토하고, 글이 매끄러운지, 부족한 내용이 있는지 확인해 글을 수정하고, 리뷰 과정을 효율화합니다.
사내 기술 블로그를 작성하거나, 개인 기술 블로그를 운영하는 분들에게 제 프로세스가 도움이 되길 바랍니다. 긴 글 읽어주셔서 감사합니다.
참고 자료
DevOps와 GitLab을 효과적으로 도입하는 방법, 지금 인포그랩에 문의하세요.