제목은 15가지인데, 뭔가 번호를 딱 찍어서 설명한 것이 아니라서 아무리 정리해도 14가지밖에 나오지 않네요. 1가지 뭔지 확인하신 분이 있다면 댓글을~
1. What's new
사례로 설명한 내용 중 Cello의 경우에는 릴리스 노트 같은 것이라서 What's new와는 좀 성격이 다르긴 합니다.
https://docs.cello.so/changelog
발표자가 작업했다는 mintblue 같은 경우는 What's new만 있고 상세 릴리스 노트가 없어서 역시 완벽하지는 않구요.
https://docs.mintblue.com/whats-new
발표자의 의도는 사용자가 문서를 보고 어떤 점이 변경되었는지 명확하게 알 수 있게 해야 한다 정도인 것 같네요.
2. 문서 검색
문서 검색 기능을 제공하는 것은 당연한 일이고 사용자의 행동 패턴을 통해 정보를 찾는 것이 중요하다고 합니다. 예를 들어 사용자가 검색을 했는데 결과를 찾지 못하는 케이스를 확인하는 것 같은 작업입니다(AI 챗봇에서도 중요하게 취급하는 내용입니다).
검색 결과 목록에서 몇 번째 항목을 클릭하는지도 중요한 지표라고 합니다. 일반적인 경우에는 상위 목록에서 찾을 수 있지만, 튜토리얼 같은 경우에는 순위가 밀리는 경우가 있다고 합니다. 이런 경우 우선순위를 지정할 수 있는 옵션이 필요합니다.
검색에서 유사한 단어를 같이 찾아주는 것도 필요합니다.
3. 데모 페이지
UI 제품의 경우 실제 제품에 특정 설정값을 바로 적용하기 부담스러울수도 있는데 데모 페이지를 통해 미리 확인하고 적용할 수 있습니다. 아마 서비스 형태로 제공되는 UI에 대한 이야기가 아닌가 싶네요. 이런 건 데모가 아니라 미리 보기 정도의 기능으로도 커버할 수 있는 것이 아닌가 싶긴 합니다만.
4. 플레이 그라운드
플레이 그라운드 사례를 소개하면서 Hedera의 경우 플레이 그라운드를 구축하는데 50만 달러가 들었다고 설명하는데 그건 아니고 플레이 그라운드를 활용한 해커톤 상금 규모가 50만 달러였다고 합니다(발표자가 참여한 프로젝트라 진짜로 그 비용이 들었을 수도 있지만, 좀 과도한 비용이긴 합니다).
https://portal.hedera.com/playground
5. trailhead approach(이정표)
랜딩 페이지를 통해 사용자가 원하는 문서를 탐색할 수 있도록 안내합니다. 모든 사용자에게 획일적인 문서화를 강요하지 마세요. 새로운 제품이라면 제품을 빠르게 소개하고 어떤 일을 할 수 있는지 탐색할 수 있게 합니다. 전체적인 이정표를 그려놓고 이를 조정하는 것이 전체 문서화를 구성하는데 도움이 됩니다.
6. sidequest hell
아마 게임 쪽 용어인 것 같은데 메인 미션이 아닌 부가적인 미션이 너무 많아 짜증나는 상황이라고 합니다. 문서에서는 추가적인 정보가 별도 링크로 제공되는데 그 내용을 보지 않으면 해당 페이지의 내용을 이해하기 힘든 상황을 이야기하는 것 같네요.
꼭 필요한 단계라면 튜토리얼 같은 경우 선행해서 학습해야 할 내용으로 링크를 제공하는 정도가 적당하다고 합니다. 중간에 끼어넣지 말고.
7. 문서 구조
이건 뭐 개론적인 이야기라서
8. super-duper-advanced-users
고급 사용자를 위한 설계 문서를 제공해야 합니다. 대부분의 문서가 초보자 또는 중금 사용자를 위한 문서만을 제공하는데, 고급 사용자를 위한 문서나 정보를 제공하는 것도 필요합니다.
9. 보일러플레이트(Boilerplate)
이것도 요즘은 기본적으로 제공되는 거라.
오히려 다른 설명 없이 해당 요소만 나열된 경우도 있긴 합니다.
10. interactive learning
처음 소개한 내용은 문서에 반영한 것은 아니고 블로그 글에 인터랙티브 애니메이션이 포함된 사례입니다.
https://encore.dev/blog/queueing#why-do-we-need-queues
11. content discoverability(검색 가능성)
외부 검색 뿐 아니라 내부 문서 필터 등의 기능을 사용해서 사용자가 문서화 페이지에서 원하는 콘텐츠를 쉽게 찾을 수 있도록 제공해야 합니다.
12. 비디오 콘텐츠
유지 보수 시 비용 문제 때문에 만들기 어려운 콘텐츠입니다. 오히려 애니메이션 같은 경우 텍스트 기반으로 작업이 된다면 비용이 줄어들 수도 있습니다(음. 애니메이션은 인터랙티브 러닝에 포함되겠네요).
13. code checks
튜토리얼을 제공할 때 꼭 사용자가 복사해갈 수 있는 코드를 제공합니다.
14. code highlighting
코드 단락에서 보통 주목해야 하는 코드 라인이 있는데 그걸 주석으로 표기하거나 특정 라인을 참고하세요. 뭐 이렇게 말고 코드 자체에 형광펜으로 표시를 해서 주목할 수 있는 기능을 제공하라는 겁니다.
Stripe 예시를 보여주었는데, 3단 구성은 더 이상 찾을 수가 없네요. 대신 코드 단락에 하이라이트 표시하는 것은 제공하고 있습니다.
https://www.moesif.com/blog/best-practices/api-product-management/the-stripe-developer-experience-and-docs-teardown/
https://docs.stripe.com/payment-links/customize?dashboard-or-api=api#collect-taxes
https://youtu.be/54neDVXwTK8?si=RwcApHujn3uKgd1Y
