개발자 문서 콘텐츠 유형
•
코드 주석
◦
코드베이스가 진화할 수록 과거에 내린 결정의 맥락을 남겨두는 것이 도움이 됨
•
README
◦
저장소에 포함된 코드 요약
◦
주요 항목
▪
코드가 상위 수준에서 하는 일
▪
설치 방법
▪
문제 해결 단계
▪
코드 유지 관리자
▪
라이선스 정보
▪
변경 로그
▪
기본 사용 예시
▪
심화 자료와 문서 링크
•
시작하기 문서
◦
제품에 관심 있는 사용자가 이 제품을 토대로 실제로 개발할 수 있도록 이끌기
◦
이 서비스가 무엇이고 서비스의 핵심 기능이 무엇인지 가장 빨리 설명할 수 있는 방법은?
◦
이 제품을 설치하고 사용하는 가장 간단한 절차는?
◦
신규사용자가 가질 수 있는 가장 중요한 질문은?
◦
사용자가 이 서비스로 할 수 있는 멋진 일은?
•
개념 문서
◦
짧고 간결하게 유지
◦
하나의 문서에서 설명하는 개념의 수를 제한할 것
•
절차 문서
◦
튜토리얼
▪
사용자가 실제로 코드를 구현하지 않고 제품과의 통합을 테스트할 수 있도록 도와주는 문서
▪
사용자가 학습에 사용할 수 있는 환경을 제공하고, 활용할 테스트 데이터나 도구를 제공
▪
단계가 10개가 넘지 않도록 구성
◦
How-to 가이드
▪
유지 관리에 비용이 많이 드므로, 사용자의 니즈와 제품의 전략에 맞는 케이스를 선별할 것
▪
필수 조건을 상단에 배치하여, 의존성이 필요한 안내를 먼저 다룸
▪
가급적 연결 링크를 최소화하여, How-to 한 페이지 내에서 사용자가 집중할 수 있도록 할 것
▪
문서 중간에 링크가 있으면 사용자의 주의를 산만하게 할 수 있으므로, 페이지의 끝에 추가 자료에 대한 링크를 제공할 것
•
참조 문서
◦
API 레퍼런스
▪
좋은 API 문서의 특징
•
모든 리소스와 엔드포인트에 대한 상세한 참조 정보를 제공합니다.
•
풍부한 예제를 제공합니다.
•
상태 코드와 오류 메시지를 나열하고 정의합니다.
◦
용어집
▪
문서에서 용어를 일관성있게 사용하는 데 동무이 됨.
▪
외부 링크를 거는 것을 제한할 것.
◦
문제 해결 문서
▪
알려진 문제나 버그에 대해 사용자가 해결할 수 이쓴 방법
▪
문제의 원인보다는 해결 방법에 집중할 것
◦
변경 사항 문서
▪
시간순으로 나열하고, 아래의 데이터를 추가할 것
•
이전에 지원되던 버전 및 통합 또는 지원 중단된 기능
•
파라미터나 중요한 필드의 이름 변경
•
옮겨진 오브젝트나 리소스
◦
릴리스 노트
▪
변경 로그에 나열된 변경 사항에 대해 풍부한 맥락 제공
▪
릴리즈 노트에 들어갈 항목
•
새로운 기능
•
버그 수정
•
알려진 버그 및 제약 사항
•
단절적 변경 등 버전 마이그레이션 관련 사항
훑어보기를 고려하여 문서 작성하기
•
기술 문서 독자에 대한 두 가지 근본적이고 역설적인 사실
◦
독자는 정보를 찾기 위해 문서를 봅니다.
◦
독자들은 여러분이 쓴 글을 매우 조금 읽습니다.
•
가장 중요한 정보를 먼저 제시하자
◦
제목은 문서의 목표를 요약해야 함
◦
처음 두세 단락에는 중요한 정보를 담아야 함
◦
작업 절차를 작성하는 경우 독자에게 문서를 읽고 나면 무엇을 달성할 수 있을지 알려줄 것
•
분량이 많은 텍스트는 나누자
◦
여러 개의 긴 단락을 하위 섹션으로 구분하기
◦
목록, 샘플 코드, 그래픽 요소로 바꿔서 훑어보기 쉽게 만들기
•
긴 문서는 나누자
◦
목적 별로 나누어서 문서를 제공하기
•
단순함과 명확함을 추구하자
◦
독자의 니즈를 충족하는 글로만 구성하기
편집에 대한 여러 가지 접근법
•
기술적 정확성
◦
누군가가 이 지시 사항을 따라가면 약속한 결과를 얻을 수 있는가?
◦
혼동을 일으킬 수 있는 기술적인 은어나 용어가 있는가?
◦
코드의 함수, 파라미터, 엔드포인트가 올바르게 명명되고 설명되었는가?
◦
중대하거나 예기치 않은 장애를 일으킬 수 있는 모든 문제에 경고성 안내 문구 작성
•
완전성
◦
콘텐츠에 사용자가 성공하는 데 필요한 모든 정보가 포함되어 있는지 확인
◦
초안에 있던 TODO나 TBD가 채워졌는지 확인
◦
사용자의 개발 환경에 대한 고려가 충분한지(리눅스, 맥OS)
◦
소프트웨어 최신 버전 대신 다른 버전을 사용하는 경우 예기치 못한 오류가 발생할 가능성이 있는지
◦
만료될 예정인 정보가 있는지
◦
버전별 제약사항이 있는지
•
구조
◦
문서 제목과 섹션 제목에서 문서가 무엇에 관한 것인지 명확히 드러나는가?
◦
문서가 일관되고 논리적인 방식으로 구성되어 있는가?
◦
문서에 다른 문서에 포함시키는 것이 더 적절한 섹션이 있는가?
◦
템플릿이 있는 경우, 문서가 템플릿을 충실히 따르는가?
◦
독자가 콘텐츠를 읽기 전과 후에 수행해야 할 작업을 나타내고 있는가?
◦
필수 조건 단계가 있다면 제시할 것
◦
독자가 문서를 읽은 후에 일반적으로 수행해야 하는 다음 단계, 필요한 추가 정보
•
명확성과 간결성
◦
최대한 명확하게 표현되었는가?
◦
일관성 없이 사용되어 수정해야 할 용어가 있는가?
◦
잘라낼 수 있는 불필요한 단어나 문구가 있는가?
◦
독자를 혼란스럽게 할 수 있는 특정 표현, 비유, 속어가 있는가?
◦
피해야 할 편향된 언어를 사용하고 있는가?
—
스스로 문서 편집 체크리스트
•
문서 제목이 짧고 구체적이다
•
섹션 제목이 논리적인 순서로 배치되고 일관성이 있다
•
문서의 목적이 첫 번째 단락에 설명되어 있다
•
절차가 테스트되었고 잘 작동한다
•
기술적 개념에 대한 설명이나 해당하는 링크를 제공한다.
•
문서가 템플릿의 구조를 따른다.
•
모든 링크가 작동한다.
•
맞춤법 및 문법 검사기를 실행했다.
•
그래픽과 이미지가 명확하고 유용하다.
•
모든 필수 조건과 다음 단계가 명시되어 있다.
샘플 코드
•
실행 가능형
◦
독자가 복사&붙여넣기할 수 있음.
•
설명형
◦
실행 가능할 것으로 기대되지 않는 형태
◦
독자가 뭔가 배우거나 자신의 코드와 비교하고자 사용하는 출력 결과나 코드 블록
•
좋은 샘플 코드의 요소
◦
설명이 제공됨
▪
전후 맥락을 제공함
▪
특정 라이브러리 설치나 환경 변수 설정 등 샘플 코드를 실행하기 위한 필수 조건이 있다면 명시해야 함.
◦
—
프로덕트 문서 — 외부 공유용 문서들
backlog, product design docs, troubleshooting 기준으로 정리
문서 배포하기
•
코드와 마찬가지로 릴리스 시점에 완벽한 문서는 거의 없다
•
문서 배포에 대한 두려움을 다루는 가장 좋은 방법은 배포 후에 피드백을 기반으로 그동안 했던 과정을 반복하는 것이다.
•
콘텐츠 릴리스 프로세스
◦
콘텐츠를 언제 배포할 것인가?
◦
최종 검토와 배포는 누가 담당하는가?
◦
콘텐츠를 어디에 배포할 것인가?
◦
콘텐츠를 배포하려면 어떤 소프트웨어 도구가 추가로 필요한가?
◦
새로운 콘텐츠를 사용자에게 어떻게 알릴 것인가?
—
문서 품질
•
목적을 달성하는 문서가 좋은 문서다
•
기능적 품질 - 문서가 목적이나 목표를 달성하는지를 의미함
◦
접근성
▪
더 많은 사용자를 고려한 접근성 — 스크린 리더 액세스 등,, ← 이건 현재 내 상황에 맞는 내용은 아니다.
◦
목적성
▪
문서의 목적이나 목표를 분명히 명시하고, 이를 달성하기 위해 노력해야 함.
◦
검색성
▪
독자가 얼마나 쉽게 찾아내고, 콘텐츠 내부에서~~ 검색하는지
▪
•
‘검색성에서 진정한 문제는 콘텐츠 깊은 곳의 잘못된 위치에 있는 독자를 콘텐츠 깊은 곳의 올바른 위치로 어떻게 이끌 수 있느냐 입니다.’
•
사용 맥락에 맞는 콘텐츠 위치 지정
•
관련 문서 간 링크 연결
•
명확한 문서 유형 사용
•
사이트 아키텍처 사용
◦
정확성
▪
문서의 내용이 얼마나 정확하고 믿을만한지
◦
완전성
•
구조적 품질
◦
문서가 잘 작성되고 잘 구조화되었는지를 의미함
조직의 목표
•
이 문서들로 달성하고자 하는것?
◦
유관 부서에 전달되지 않아서 발생하는 오류를 없앨 것…
▪
생각보다 작은 부분에서 전달되지 않아 발생하는 오류가 많음. (api 스펙이 변경되거나 했을 때, 개발팀에서는 작은 이슈라고 생각하는게 유관부서는 큰 일 일수도 있고.. 그 부분을 어떻게 관리해야 할지..??)
▪
이런 부분들을 이걸로 해결할 수 있으면 성과가 되긴할텐데 흠.. 떠먹여 줄리는 없으니 떠먹어야 하긴 함…
문서 구조화
•
와… 아니 구조화라는 단어는 나 혼자 생각해내서 했던 건데, 여기서 책 한 챕터로 다루고 있네?
•
점점 더 많은 페이지를 게시함에 따라, 독자들이 탐색하고 이해하기 어렵다고 느낄만큼 콘텐츠가 정리되지 않은 채로 늘어났음을 알게 될 수 있습니다. 문서를 구조화하는 방법에 대해 생각해야 할 때가 된 겁니다.(215p.)
•
콘텐츠를 구조화하는 방법을 정의해 두면 문서를 체계적이고 지속 가능한 방식으로 확장하는 데 도움이 됩니다. 콘텐츠를 구조화하는 방법은 독자에게 콘텐츠의 의미와 목적을 전달합니다. 문서에 적용하는 조직화된 구조를 정보 아키텍처information architecture 라고 합니다.
•
정보를 의미 있는 구조로 조직화하고, 의도적으로 콘텐츠 구조의 패턴이 드러나도록 하고, 사용자와 가장 관련이 있는 정보를 강조하여 사용자가 사이트를 더 빠르고 직관적으로 탐색하도록 도울 수 있습니다. (216p.)
•
근데 내가 문서를 구조화할 때 중점으로 두었던 것이 무엇이었을까? 중점으로 둔 사용자가 누구였는지에 대해서 고민이 되는 지점
•
문서를 구조화한다는 것은 기존 콘텐츠를 평가하고, 정보 아키텍처를 계획하고 구축하며, 콘텐츠를 이 새로운 조직 체계로 마이그레이션하는 것을 의미합니다. 구조화의 목표는 사용자가 필요한 것을 찾는 데 도움을 줄 뿐만 아니라 시간이 지나도 유지 관리하고 확장하기에 용이한 최상의 콘텐츠 조직 구조를 만드는 것입니다. (224)
•
문서를 구조화하고 정보 아키텍처를 구축하는 첫 번째 단계는 기존 콘텐츠의 평가입니다. 이 작업의 목표는 여러분이 현재 갖고 있는 모든 콘텐츠의 목록을 만들고 각 콘텐츠의 위치가 사용자에게 얼마나 많이 도움이 되는지 파악하는 것입니다.
•
평가 과정을 사이트 최상위 수준에서 시작하여 문서의 각 페이지를 거쳐가는 순서도로 생각하세요. 먼저 사이트에 있는 전체 문서 페이지의 제목과 URL을 스프레드 시트에 나열해봅니다. 그런 다음 사용자에 대해 알고 있는 정보로 목록의 각 페이지를 평가하여 각 페이지가 얼마나 잘 작동하는지 확인합니다.
•
각 페이지를 평가하면서, 페이지에 수행해야 할 작업으로 레이블을 지정하세요. 레이블의 예는 다음과 같습니다.
◦
유지, 제거, 정확성 검토, 다른 문서와 병합, 여러 문서로 분할
•
문서가 여러 위치에 들어맞는 경우는 어떻게 해야 할까요?
◦
가장 적합한 위치 한 곳에 두고 링크로 연결하래!
•
정보 아키텍처 자체 문서화 ← 이게 있어야 할듯!
◦
결정된 사항, 결정의 기반이 된 …
유지 관리하는 방법
•
이 새로운 콘텐츠가 들어갈 위치가 명확한가?
•
기존 정보 아키텍처에 어떤 조정이 필요한가?
•
이 콘텐츠가 사이트 홈페이지나 랜딩 페이지에 영향을 주는가?
문서를 최신으로 유지하기
•
개발자들은 기본적으로 문서를 잘 신뢰하지 않는 경향이 있다고 봄… ← 문서는 최신화되어 있지 않을것이다~ 라고 생각하는..? (이래서 내가 고찰하게 된다는 점임.. 이것의 궁극적인 해결이 가능할까? 문서를 봐도 어차피 도움이 안돼. 라는 생각에서 벗어나게 할 수 있는 방법이 있기는 할가? 오히려 1:1로 물어볼 수 있게 하거나 챗봇을 활용하는게 더 패러다임을 바꿔서 해결할 수 있는 부분일지도 모름)
•
문서로 독자에게 변경 사항에 대한 정보를 제공하고, 지원 중단된 기능 대신 그들의 니즈를 가장 잘 해결하는 기능으로 사용자를 이끌어 사용자 경험을 개선할 수 있습니다.
◦
또한 문서에서 독자가 변경 사항에 대해 가질 수 있는 질문에 사전에 답할 수 있으므로 독자에게 최신 정보를 반영한 최상의 제품 경험을 제공할 수 있습니다.
•
유지 관리하기 위한 계획 세우기
◦
코드 작성과 문서 작성의 방향을 맞춰야 함.
◦
새로운 기능을 설계할 때 코드와 콘텐츠 둘 다에 어떤 업데이트가 필요할 지 고려해야 한다.
◦
새 기능 때문에 API를 변경하거나 사용자가 애플리케이션의 다른 부분과 상호 작용하는 방식을 변경하는 경우, 문서를 통해 사용자에게 알려야 합니다. 이에 따라 계획을 세우세요.
•
문서화를 릴리즈 프로세스에 통합하는 작업
•
업데이트된 문서와 코드는 동시에 릴리즈 되어야 하며, 서로 동기화된 상태를 유지해야 함.
•
문서화와 코드 릴리즈의 방향을 맞추는 방법
◦
릴리즈에 필요한 각 문서 업데이트에 대한 추적 이슈 또는 버그 티켓 만들기
◦
스프레드 시트로 문서화 니즈를 기능 요청과 함께 추적.