테크니컬 라이팅 (문서 작성 가이드)

마이클의 AI 연구소·2022년 9월 16일

개요

개발 프로세스에 있어 문서화는 옵션이 아닌 필수입니다. 또한 개발 문서는 회사 및 팀의 자산이 되는 공용 자원입니다. 따라서 개발 프로세스 내에서 작성되는 문서들은 개인적인 문서작성 습관이 아닌 일관된 작성 원칙을 따라 작성되는 것이 좋습니다. 본 문서에서는 문서의 글쓰기 원칙과 문서 포맷에 대한 가이드라인을 제시하도록 합니다.

글쓰기 원칙

명확성

글쓰기의 원칙은 명확성입니다. 명확한 글이란 핵심어나 핵심 문장이 모호하게 사용되지 않고 대상 독자가 기술문서를 읽을 때 내용의 모호함이나 혼란 없이 한 번에 이해하도록 하는 글입니다. 어떤 문서를 읽을 때 독자 입장에서 이해가 가지 않아 특정 부분을 몇 번이고 다시 읽게 된다면, 이는 명확성이 떨어지는 글입니다.

두 가지 문장을 비교하여 봅시다.

관리자 설정 기능은 관리자를 등록한 후에 사용할 수 있으며 사내 이메일 계정이 사용됩니다.

사내 이메일 계정을 사용하여 관리자를 등록한 후에 관리자 설정 기능을 사용할 수 있습니다.

첫번째 문장의 경우 사내 이메일 계정이 어디에서 사용되는지 앞쪽 내용을 통해 유추해야 합니다. 그러나 두번째 문장은 이메일 계정을 어디에 사용해야 하는지 명확해집니다.

다양한 예들을 통해 문장을 살펴봅시다.

	원본	수정본
출처가 명확하지 않은 소프트웨어를 설치하지 않습니다.	출처가 명확한 소프트웨어만 설치합니다.	이중 부정 지양
홈페이지 2.0이 오픈합니다.	홈페이지 2.0을 오픈합니다.	문맥에 맞는 조사사용
아래의 3가지 항목에 대한 설명을 확인하시고 설정하세요.	아래의 3가지 항목에 대한 설명을 확인 후 설정하세요.	중복 높임 지양

간결성

간결성이란 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구나 감탄사 등은 사용하지 않고 간단하고 쉬운 단어와 간결한 문장을 사용하는 것입니다.

A 속성은 정의된 인터페이스의 namespace 부분을 기술하는 부분으로 이름과 버전명을 명시하며 이름은 해당 API를 타겟팅하고 버전은 API 서버와 Capability 제어를 위해 사용할 수 있습니다.

A 속성은 정의된 인터페이스 이름과 버전 정보를 기술하는 부분입니다. 여기서 ‘이름’은 해당 API 서버명이며, ‘버전정보’는 추후 API 서버와 Capability 제어에 사용됩니다.

간결성에 원칙에 따라 수정문에서는 A 속성에 대한 정의를 직관적으로 한 줄로 정리하고, A 속성과 관련된 부연 설명을 다음 문장에 정리했습니다. 필요한 정보는 모두 전달했지만 문장 길이는 줄고 가독성도 높아졌습니다.

다양한 예들을 통해 문장을 살펴봅시다.

	원본	수정본
인증메일을 성공적으로 전송했습니다.	인증 메일을 전송했습니다.	불필요한 표현 제거
선택하신 파일을 삭제합니다. 정말 삭제 하시겠습니까?	선택한 파일을 삭제하시겠습니까?	불필요한 표현 제거
등록한 시간 만큼은 근무시간에 포함되지 않습니다.	등록된 시간은 근무시간에서 제외됩니다.	긍정문을 활용하여 간결하게
세션 정보는 계속 유지됩니다.	세션 정보는 유지됩니다.	중복 표현 지양

문서 작성 양식

실제 문서 작성시 적용할 문서 작성 양식을 설명합니다.

개요 작성하기

다음과 같이 문서의 가장 첫머리에 문서 전반적인 내용을 아우르는 한 두 문장의 설명을 작성합니다. 작성 후, 구분자를 추가하여 본격적인 문서의 내용이 시작됨을 표현합니다. 컨플루언스 문서편집기에는 구분자 삽입 기능이 있습니다. /를 입력 후, divider 를 입력하면 구분자를 사용할 수 있습니다.

실제 예는 다음과 같습니다.

목차 삽입하기

컨플루언스 문서편집기에는 목차 삽입 기능이 있습니다. /를 입력 후, table of content 를 입력하면 목차를 사용할 수 있습니다. 삽입되면 자동으로 헤딩(heading)을 인식하여 다음과 같이 목차를 만들어줍니다.

컨플루언스에서는 아이러니하게도 목차를 헤딩으로 입력하면 목차 내부에 ‘목차’까지도 출력되므로 목차의 예외를 등록해야 합니다. 목차 클릭 후, 펜 모양 버튼을 누르면 화면 우측에 설정 위젯이 출력되는데 거기서 예외등록란에 .목차. 라고 입력하면 목차라는 키워드는 목차에서 제외하게 됩니다.

헤딩(heading) 사용하기

컨플루언스에서는 #을 통해 헤딩을 선택할 수 있습니다. #은 헤딩1, ##은 헤딩2, ###은 헤딩3을 의미합니다. 내용의 구조에 따라 헤딩을 적절히 사용하여 작성합니다.

헤딩1과 헤딩2는 크기가 다르지만 명확한 구분이 안됩니다. 따라서 헤딩1의 경우 드래그 후, Ctrl + B를 하여 Bold를 설정해주어 더욱 명확하게 보이도록 하는 것이 좋습니다.

패널(panel) 사용하기

컨플루언스에는 패널 삽입 기능이 있습니다. / 입력 후, panel을 치면 다양한 사전정의된 패널을 사용할 수 있습니다. 어떤 패널이든지 삽입 후, 편집기능을 통해 아이콘을 변경하거나 없앨 수 있습니다.

다음과 같은 방식으로 패널을 사용하여 중요한 부분들을 강조하거나 보기 좋게 합니다.

패널 아이콘 없앤 후, 색상 그레이로 변경

다양한 패널의 아이콘 및 색상

불릿 사용

불릿은 * 입력하여 사용할 수 있습니다. 불릿을 남용하기 보다는 보통은 문장 형태를 취하되, 나열이 필요한 곳에 사용하는 것이 좋습니다. 불릿은 주로 문장보다는 단어형태다 명사형 종결문(-음, -함)체를 사용하는 것을 권장합니다. 불릿을 여러단계로 두는 것은 가독성을 해치므로 지양해야 합니다.