개발자의 글쓰기 : Technical Writing #4

[eagle705]

개발자 글쓰기 4편 요약 (feat. ChatGPT)

내용	주요 내용
들어가며	개발자 글쓰기 1,2,3편을 이어 Docs for Developers 기술 문서 작성 가이드를 기반으로 한 4편 작성. 이번 글은 작성된 문서의 피드백 및 품질 측정에 중점을 둠.
Ch 8 피드백 수집하고 통합하기	- 피드백 수집 시 제품 및 문서 지적 내용 정리 필요 - 사용자 피드백 채널 생성 (예시: Github issue) - 문서 감정 수집 및 사용자 설문조사로 CSAT 도출 - 사용자 위원회 구성 가능
Ch 9 문서 품질 측정하기	- 문서 품질 이해: 기능적 품질 (가독성, 목적성, 검색성, 정확성, 완전성), 구조적 품질 (명확성, 간결성, 일관성) - 문서 품질 메트릭: 순 방문자수, 페이지 조회수, 페이지에 머문 시간, 이탈률 등 다양한 메트릭 활용
Ch 10 문서 구조화하기	- 정보 아키텍처: 독자를 위한 조직화된 구조 구현 - 랜딩 페이지, 탐색 신호, 사이트 탐색 구조를 활용하여 사용자 경험 개선 - 아키텍처 윤곽: 일관성, 관련성, 검색성을 고려하여 정보 아키텍처 설계 및 구현
마치며	개발자 글쓰기는 문서도 하나의 제품으로 취급해야 하며, 피드백 프로세스와 문서 품질 측정을 위한 체크리스트를 활용하여 품질을 향상시킬 수 있다. 문서의 정보 아키텍처는 랜딩 페이지, 사이트 탐색 구조, 탐색 신호를 고려하여 독자를 위한 최적의 구조로 설계되어야 함.

들어가며

안녕하세요.

개발자 글쓰기 1,2,3편에 이어 4편을 작성하게 되었습니다.

해당 내용은 스터디 메이트 활동의 일환으로 Docs for Developers 기술 문서 작성 완벽 가이드 라는 책의 내용을 기초로 작성되는 점 안내 드립니다.

이번에 작성되는 내용은 작성된 문서의 피드백 및 품질 측정에 관련된 내용을 주로 다루게됩니다.

느낀점
문서도 하나의 프로덕트로 보는 듯함
문서에 대해서 평가할때 어떤 기준을 체크리스트로 만들어서 평가하면 좋을지 배울 수 있음

Ch 8 피드백 수집하고 통합하기

• 피드백을 수집하다보면 어떤 내용은 제품문제를 다루고 어떤 내용은 문서를 지적하기도 함
• 피드백 받는 것도 정리가 필요함

필요한 작업들

• 사용자 피드백 채널 만들기
• 피드백에 대한 조치 취하기
• 사용자로부터 받은 피드백 분류하기

사용자 피드백 채널 만들기

• 유용한 정보를 가장 적은 시간, 비용으로 받아낼 수 있게
• 문서 페이지에 직접 피드백 받기(github issue?)
  • 템플릿을 사용하면 좋음

예시1	feature request

• 문서 감정 수집 (document sentiment)
  • "이 페이지가 도움이 되었나요? Yes / No"

문서 감성수집 예시	이미지
페이스북

• 사용자 설문조사 만들기
  • CSAT(customer satisfaction score) 도출에 도움이 됨

정의	계산

• 사용자 위원회 만들기
  • 사용자수가 적다면 구성하기 도함 (얼리어답터, 잠재적 사용자로 이루어짐)

피드백에 대해 조치 취하기

• 피드백 '단계별' 분류하기

  • 1단계: 문제가 유효한가?
  • 2단계: 문제를 해결할 수 있는가? (재현이 가능해야)
  • 3단계: 문제가 얼마나 중요한가?

• 사용자에게 후속 조치 취하기

  • 릴리즈 노트때 사용자를 언급
  • 피드백에 감사를 전하기

Ch 9 문서 품질 측정하기

내가 쓴 문서 괜찮은걸까?

이번 챕터에는 다음과 같은 내용을 다루게 됩니다.

• 문서 품질 이해하기
• 문서 분석 전략 세우기
• 메트릭을 품질에 맞춰 조정하기
• 여러가지 메트릭 함께 활용하기

문서 품질 이해하기

• 문서품질의에 대한 구글의 정의목적을 달성하는 문서가 좋은 문서다
  • 기능적 품질
  • 구조적 품질

기능적 품질

• 접근성
  • 언어, 고등학교 1~2학년 수준, 자동화된 가독성 지수(automated readability index, ARI), 콜먼-리아우 지수(Coleman-Liau index)

가독성지수 수식	점수표

• 목적성
  • 제목과 첫번째 단락에 명시
• 검색성
• 정확성
  • 잘 작동하는 샘플 코드 및 명령어 예제와 더불어 기술적 설명 기재
• 완전성
  • 독자가 따라야하는 모든 필수 요건 나열
  • 작업을 완료하는데 필요한 모든 작업 문서화
  • 독자가 취해야할 다음 단계를 정의

구조적 품질

문서가 얼마나 읽기 쉬운지 (문장, 단락, 제목구조, 언어품질, 문법 정확도 등등)에 대해서 3C로 정의

• 명확성(Clarity)
  • 주제를 논리적으로 나눔
  • 작업 단계를 시간순으로 기대하며 각각의 기대 결과를 나타내는 섹션 제목
  • 프로세스의 각 단계에 대한 명확한 결과
  • 독자가 막힐 가능성이 있는 모든 위치를 미리 알려줌
• 간결성(Conciseness)
  • 관련성이 있지만 곧바로 필요하지 않은 모든 내용은 링크로 제공
  • 헤밍웨이 에디터 처럼 문서의 간결성을 측정하고 개선하는데 사용할 수 있는 도구가 있음
    • 
• 일관성(Consistency)
  • 같은 개념에 대해 같은 용어와 표현 사용 (API에 인증하기 != API에 연결하기)

문서의 목표와 메트릭

수집할 수 있는 메트릭 리스트

• 순 방문자수: 얼마나 많은 사용자가 문서를 읽고 있습니까?
• 페이지 조회수: 어떤 문서를 가장 많이 보고 잇습니까?
• 페이지에 머문 시간
• 이탈률
• 검색 키워드 분석: 사용자가 문서를 어떻게 찾고 있습니까?
• 읽기 수준 분석
• 문서와 관련된 고객 지원 문제
• 링크 유효성 검사: 문서에 수정해야할 문제가 있습니까?
• 타임 투 헬로 월드 (새로운 프로그래밍 언어로 Hello World 프로그램을 작성하거나 서비스로 간단한 작업 수행하는데 걸리는 시간): 제품 사용을 시작하는데 얼마나 걸립니까?

요약

• 기능적 품질과 구조적 품질을 검토
• 독자의 목표와 조직의 목표가 서로 방향이 일치하는지 확인
• 메트릭 기준선 설정 후 정량적 정성적 피드백을 모두 고려

Ch 10 문서 구조화하기

독자를 위해 문서 구조화 하기

문서에 적용하는 조직화된 구조를 정보 아키텍처(information architecture)라고 합니다.

• 독자가 올바른 컨텐츠를 찾도록 돕는방법
• 정보 아키텍처 설계하기
• 정보 아키텍처 구현하기

독자가 길을 찾도록 돕기

• 사이트 탐색 구조
• 랜딩 페이지
• 탐색 신호

사이트 탐색 구조

• 순차구조

  • 모든 독자에게 가장 익숙한 구조 (책)
  • API 사용시 필요한 단계처럼 시간순, 색인이나 용어집처럼 알파벳순
    

• 계층구조

  • 가계도나 조직도와 유사함
  • 컨텐츠 페이지간에 부모/자식 관계가 있음
  • 넓은 아이디어로 시작해서 점점 더 상세하고 구체적인 정보로 범위를 좁힘
    

• 웹구조

  • 서로 페이지가 연결된 비계층적 패턴
  • 각 페이지가 하나 이상의 페이지와 연결됨
  • 각 페이지는 계층 구조상 동일한 수준에 있으므로 한 주제에서 다음 주제로 끊김없이 이동가능
    

• 모두 한 데 모으기

  • 대부분의 사인트는 위 3가지 구조를 조합해서 사용함
  • 계층 구조였다가 각 섹션에 어떤 작업을 해야되는지 단계별로 설명하는 식으로 변경가능
    

랜딩 페이지

• 사용자가 컨텐츠를 가능한 적게 읽고도 올바른 컨텐츠로 안내 (READMD.md 와 같은 역할)
• 서비스의 개요와 짧은 튜토리얼이 포함된 시작하기 세션
• 가장 많이 사용되는 두가지 작업에 대한 How-to 가이드

탐색신호

• 대부분은 검색엔진 사용
• 한번에 찾기 어렵기 때문에 얼마나 정보에 가까이 있는지 도움을 주는 신호가 있으면 좋음
• 다음의 요소들이 사용됨
  • 이동 경로: 상하위 컨텐츠
  • 측면 탐색 메뉴: 전체 사이트 또는 특정 영역의 컨텐츠 계층 구조를 보여줌
  • 레이블과 메타데이터: 인덱싱에 도움이 되도록 기계가 읽을 수 있는 형태로 되어있음
  • 필수 조건, 다음단계, 추가 정보 섹션
  • 탈출용 해치: 대신 방문할 페이지 추천

아키텍쳐 윤곽잡기

다음의 요소로 디자인해야함

• 일관성
• 관련성
• 검색성

다음의 체크 리스트로 새로운 구조의 유호성을 평가하면 좋음

요소	설명
랜딩 페이지	사용자를 가장 중요한 문서로 안내
컨텐츠 유형	지속적으로 만들어지는 문서이면서 사용자에게 적합해야함
페이지 데이터	페이지 제목, 섹션 제목, 필수조건, 다음 단계가 이해하기 쉽고 일관성 있어야함
탐색 신호	이동 경로, 측면 탐색메뉴, 탈출용 해치 활용해서 사용자가 현재 위치를 알수있어야함
레이블과 메타데이터	사용자 및 검색 인덱스와 관련있는 데이터 표시
리디렉션	페이지를 옮긴 후에 사용자를 이전 위치에서 새 URL로 리디렉션 해줘야함

참고

문서가 여러 위치에 들어맞는 경우에는 어떻게 해야할까? 재사용이 매력적인 옵션으로 보일 수 있지만, 검색결과의 정확성을 낮추거나 독자에게 혼란을 줄 수 있고 유지관리가 어려움. 문서를 가장 적합한 위치 한곳에 두고 필요에 따라 다른 곳에서 해당 문서를 링크로 연결하는 것이 더 나은 방법임

마치며

흔히 개발할때 어떤 프레임워크는 문서가 친절하다 아니다라는 말을 종종 하게됩니다. 문서 또한 하나의 프로덕트로 보고 개발 및 배포하게 된다면 위의 가이드를 체크리스트 삼아 피드백 프로세스 및 문서의 품질을 끌어올리는데 좋은 레퍼런스가 되지 않을까 생각해봅니다.