개발에 대해서 배우고 있는데, 자신에 대한 기준이 엄격하기 때문인지 구현이 두렵다. 또한, 나는 기획하고 프로젝트를 총괄하며 원활히 진행되도록 일조하는 일을 좋아하고 잘한다고 생각하기때문에 이 단계부터 알아가보려고 한다.

우선 프로젝트 순서를 이해하고, 내가 담당하여 작성할 개발문서에 대해 이해해보는 시간을 갖기로 했다.
이하의 내용들은 내 생각과 더불어 인터넷 세상의 많은 경험들을 참고하여 작성했다.

기획단계에서 필요한 프로젝트 문서

기획문서

기획문서는 프로젝트 시작 "전" 단계에서 정의해야할 내용을 작성한다.

개발 범위 및 전체 일정

어떤 프로젝트를 진행하건 프로젝트의 최종 목표가 무엇인지, 워크 플로우와 일정은 어떻게 되는지 수립하는 것은 프로젝트가 잘 굴러가도록 하는 요소 중 하나라고 생각한다. 많은 사람들이 협업하여 일하는 만큼 자신이 지금 어떤 트랙에서 어딜향해 달려가고 있는지를 잘 아는 것이 중요하다는 것이다.

시스템 구성도

개발, QA 관련 인스턴스 테스트 DB 정보 등을 식별하는 것으로, 이를 통해 추가 장비나 예산을 정할 수 있다고 한다.

이해관계자

커뮤니케이션할 담당자(책임자..)를 지정한다.

R&R 정의

업무분장은 프로젝트 진행에서 정말 중요하다. 앞서 말했듯, 내가 무엇을, 네가 무엇을, 우리가 무엇을 하고있는지 아는게 중요하기 때문이다.

시스템 흐름도

기획자와 개발자 간 원활한 소통을 위해 PPT 한 장에 전체적인 흐름을 정의한다.

화면 정의서

기획자와 개발자가 같은 도면을 생각하고 일할 수 있도록 돕기에 확정된 상태여야 한다. 이를 기반으로 DB 설계와 프로세스를 정의할 수 있기 때문이다.

프로세스 정의서

화면에서 데이터가 어떻게 처리되는지, 어떤 이벤트가 발생하는지 식별한다. 화면 이외의 CRUD 과정에서 어떤 데이터가 처리되는지도 정의해야 한다.

용어사전

DB 테이블 명과 칼럼 명을 생성해야한다. - 클래스명, 변수명도 함께 결정되기 때문이다.

공통 코드 정의

필요한 공통코드 정보를 API에서 제공하고 공통 화면에서 AJAX를 통해 가져다 쓰게 정의하여 사용하는 등 개발 소스를 관리한다.

Code convention

네이밍 규칙 및 변수 생성 등은 사전에 정의하고 공유해야한다.

기술 문서 작성 5단계

1. 문서 기획

PM과 함께 테크니컬 라이터는 문서 작성 범위, 문서 이해관계자, 프로세스, 문서 작성 도구, 파일 형식, 문서 일정을 정의한다.
문서는 개발 Phase나 산출국가에 따라 언어나 콘텐츠가 다양해질 수 있기에 작성 범위를 정의하는 것이 중요하다.
위에서 언급한 개발 이해관계자에는 책임자라고 적어뒀지만, 문서에 관련해서는 초안 작성자, 테크니컬 라이터, 문서 검토자, 피어리뷰 진행자, 문서 최종 승인자, 문서 배포자 등 다양한 역할이 존재할 수 있다. 또한 여기서의 프로세스는 프로젝트 특성에 따른 문서 작성의 프로세스를 의미한다. 문서 작성 도구는 회사의 규모나 조직 문화에 따라 달라질텐데, 이는 한 회사 내에서도 부서별로 사용하는 문서 도구가 구글 닥스인지, 노션인지, 마크다운인지에 따라서 다르기때문에 하나로 정하는 협의 과정이 필요한 것이다. 파일 형식 역시도 export할 것을 고려하여 pdf, html 5 등을 정해야한다. 만일 web으로 제공하면 보안 사항도 함께 정의해야 한다. 문서 일정은 문서 작성도 하나의 프로젝트이기에 문서 자체가 어떤 디벨롭 과정을 거쳐야하는지 그 일정이 수립되어야 효율적으로 작업할 수 있기에 정해야한다.

2. 목차 구조화

초안 작성자와 테크니컬 라이터는 회의를 통해 문서의 목차를 함께 구성한다. 시작이 반이라는 말이 이때 쓰이는데, 목차만 잘 구성해도 문서 작업의 절반이 끝난 것과 다름 없다.

문서를 구조화할 때 레퍼런스 문서를 분석하고, 독자의 평의성을 고려해야하는 등 고려할 점이 많다.

카카오엔터프라이즈의 테크니컬라이팅 팀에서는 자체 용어 정리, 템플릿, 기술 문서 규칙, 목차 구성 방법 및 요청을 서로 공유하고 있다.

3. 문서 작성

본격적으로 문서를 작성하는 방법은 초안 작성과 리라이팅이다. 문서 작성은 개발 세부 단계마다 작성될 필요가 있다. 만일 개발을 모두 완료한 뒤 문서를 작성하면, 개발과 관련된 다양한 이유(이슈 대응, 긴급 프로젝트 투입 등)로 쉽게 부실한 문서가 되기 때문이다.

초안 작성

카카오엔터프라이즈의 글에 의하면 ISO/IEC 표준에 따르면(글 작성에도 ISO표준이 있는지 몰랐다.) 문서 한 페이지의 초안을 작성하는 데 1시간이 소요된다. 하지만 우리는 시간을 글쓰는데 투자하지 않는 경향이 있다. 개발도 하면서 문서도 작성하려고 한다면, 문서 작성 일정을 지키지 않는게 계속해서 쉬워질 것이다. 우리는 이러한 딜레이 현상을 최대한 지양하고, 다음 단계인 리뷰 단계에 할애할 충분한 시간을 보장하여 문서의 품질을 높이는 것이 중요하다.

리라이팅

테크니컬 라이터는 개발자가 생략한 "개발자라면 알 것"이라 생각한 내용을 보완 및 수정하여 회사 외부의 초급 개발자들도 쉽게 따라 할 수 있도록 상세히 작성한다. 또한 테크니컬 라이팅은 명확성, 간결성, 정확성, 일관성이라는 4대 원칙이 있다. 테크니컬 라이터는 작성된 초안을 원칙에 입각하여 가독성과 사용성이 높은 문서로 만들어낸다. 이때 기술적인 내용을 정확히 알아야 초안을 수정할 수 있기 때문에 초안 작성자에게 관련 교육을 요청하고, QnA를 주고받는 작업이 진행된다. ISO 표준에 따르면 수정/편집은 각각 0.5시간과 ~2.5시간이 소요된다고 한다.

4. 리뷰

리뷰 단계에서는 기술적인 측면과 스타일적인 측면에서 문서를 점검한다. 기술적인 리뷰는 초안 작성자와 다른 개발자가 함께 진행하여 문서의 기술적인 내용에 오류가 없는지에 초점을 맞춰 진행한다. 스타일적인 리뷰는 피어 리뷰라고도 하는데, 동료 테크니컬 라이터와 문서의 표현, 용어, 스타일 가이드, 맞춤법 등을 리뷰하는 과정이다.

만일 수정 보완 사항이 발견되면, 다시 "작성" 단계로 돌아간다.

ISO 표준에 따르면 페이지 당 내용 리뷰는 30분, 단순 교정 작업은 약 15분이 소요된다.

5. 배포

요즘에는 웹으로 문서를 배포하는 것이 추세이다. 누구나 쉽게 URL로 문서에 접근할 수 있기 때문이다. 만일 접근에 제한이 필요한 경우 PDF 포맷이나 Google Docs를 이용하여 권한을 제한하기도 한다. 테크니컬라이팅 딤에서는 문서 배포 이후의 문서 데이터베이스, 버전 관리도 진행한다.

예시 포맷

제목
목차
목차 별 페이지 제공
문서 정보
문서명,
작성일,
버전
저작권

🔻 How

1. 친절한 설명

README를 읽어보기.

2. Markdown 문법으로 작성
   보다 간편한 마크업 페이지 구성을 위해 Markdown 으로 작성한다.
   Typora라는 에디터는 렌더링된 화면(프리뷰)을 보여주기 때문에 효율적으로 문서를 작성할 수 있다.

3. 표와 이미지를 잘 사용하기
   카카오 개발자 문서 페이지에 들어가보면 친절한 설명과 다수의 표와 이미지를 볼 수 있다. 사람을 글을 읽기 귀찮아한다. 적어도 나는 그렇다. 따라서 긴 정보는 표와 이미지를 이용해서 압축하는 것이 좋다.

Reference

개발자 관점에서 필요한 프로젝트 문서
카카오엔터프라이즈-기술문서작성 5단계
Kakao Developers 문서