도마 위의 생선은 다음과 같다.
Kakao developers 카카오 로그인:
https://developers.kakao.com/docs/latest/ko/kakaologin/common
Kakao developers 사용자 관리:
https://developers.kakao.com/docs/latest/ko/user-mgmt/common
수술을 시작하겠습니다.
ISO/IEC/IEEE 26514
: 2022
톺아보기안녕하세요.
테크니컬 라이터 Janghyun lee입니다.
지난 시간에는 백 번, 천 번을 강조해도 과함이 없는 보안 이야기(API 보안)를 전해드렸다면
이번 시간에는 ‘표준화와 스탠다드(Standardization)’에 대해 이야기해보고자 합니다.
Global Standard를 준거로 세운 전략을 통해, 카카오 기술문서의 일부(Account, Log-in, etc.)를 디벨롭하는 시간도 가져보겠습니다.
2022년도 어느덧 끝을 향해 달리고 있습니다. 2023년을 기다리시는 분들도 계시겠지요.
특별히 올 한 해를 강렬하게 인지하고 있을 IT 업계의 종사자들을 떠올려봅니다.
‘기술 문서’를 관리하는 테크니컬 라이터나 개발팀의 기술 관리자(개발자 및 엔지니어)에게 2022년은 완전히 새로운 한 해였기 때문입니다.
올 초, 개정된 ISO/IEC/IEEE 26514:2022
이 발표되었습니다.
참고로 2008년 버전이 가장 최근 에디션이었습니다.
새 에디션 환영합니다! 축하합니다!
하드웨어와 소프트웨어를 포함한 STEM 산업 종사자들에게 ISO (International Organization for Standardization)는 참 고맙고 듬직한 단체입니다.
스위스 제네바에 본부를 두고 있는 ‘국제 표준화 기구’로 많이 알려져 있죠.
ISO는 강제력이 없는 비정부 기구로서 전 세계에 많은 회원국을 거느린 조직으로 강제력은 없지만, 워낙 오래되고 영향력이 크다 보니 ISO에서 발의된 표준 권고 규격은 회원국들 내에서는 협약을 통해 바로 제도화되는 편입니다.
ISO는 많은 산업 분야 내 상품의 품질, 생산 환경, 유지 보수 및 안전 등 정말 다양한 분야에 대해 ‘표준화 규격’을 연구하고 제작해 세계 각국에 제안하는 역할을 합니다.
글로벌 표준을 만들어 다양한 나라가 동일한 표준 위에서 소통하고 개발하며 인류에 기여하는 기술로 발전시키는 것을 목표로 합니다. 실제로 UN과 함께 SDG (Sustainable Development Goals)라는 조직 및 아젠다를 운영하며 이 가치에 기여하도록 ISO의 글로벌 표준이 동작하고 있는 것을 알 수 있습니다.
https://www.iso.org/sdgs.html
이제, ISO가 발표하는 많은 표준들 중 우리에게 가장 중요한 매뉴얼이 될 ‘26514’에 대해 알아봅시다.
ISO/IEC/IEEE 26514는 소프트웨어 제품 사용자를 위한 정보의 설계 및 개발에 대한 요구사항을 제공합니다. 프로젝트 목표 및 목표 설정, 청중 및 작업 분석, 정보 수집을 포함하여 정보 아키텍처 및 개발 활동을 정의하고, 품질의 원칙을 식별하는 기준을 만듭니다.
개념 정보, 지침 정보, 참조 정보, 문제 해결 정보와 같은 소프트웨어 특정 기능에 특히 주의하여 사용자를 위한 정보의 구조, 내용 및 형식에 대한 요구 사항을 지정하고 API(응용 프로그래밍 인터페이스) 및 챗봇, 스타일 가이드를 준비하며 번역되거나 현지화될 정보를 개발하기 위한 유익한 지침을 제공합니다.
결국, 우리가 세계 공용어인 ‘영어’를 공부하고 사용(해야)하는 것과 같은 이치입니다.
하지 않으면 불편해지고 때로 위험해지기도 합니다(broken English usage).
‘언어’란 그 자체로 사회의 공기이기 때문입니다. 무서운 이야기일 수 있지만 실제로 무서운 일이기도 합니다.
“지구에는 80억 명의 사람들이 있고요 한국에는 5,000만 명이 있습니다.”
— 김동신 대표, Sendbird
프로그래밍 언어가 존재하는 것처럼 IT 서비스를 이루고 있는 서비스 문서(기술 문서)에도 약속된 ‘언어 또는 약속과 문화’가 있(었)구나 정도로 이해하시면 됩니다.
이해만 하면 끝날까요?
아닙니다. 실행은 뒤에서 저와 함께 하시면 됩니다.
2022년, 바로 이 ‘약속’이 오랜만에 개정되어 발표되었습니다.
2008년 버전과 얼마나 달라졌을까요? ISO는 대단하게도 이를 아래와 같이 공개하고 있습니다.
Compare ISO/IEC/IEEE 26514:2022 with previous edition ISO/IEC 26514:2008
아래 모든 소스의 출처는 이번 2022 개정판입니다.
This first edition cancels and replaces ISO/IEC 26514:2008, which has been technically revised.
The main changes are as follows:
— increased emphasis on designing and developing information for users of software;
— use of IEC/IEEE 82079-1 as a normative reference for information for use;
— addition of subclauses regarding application programming interfaces (API) and chatbots.
“사용자! (서비스) 사용자! (제품) 사용자!”
이번 2022 개정판의 가장 큰 키워드이자 ISO가 강조하고 있는 단어는 바로 ‘사용자 Users’입니다. 너무 당연한 이야기가 아닌가 하실지 모르겠습니다.
하지만 재밌는 사실은 과장 없이 거의 모든 문장과 문단에서 ‘Users’를 강조하고 있는데요. 내용 면에서도 사용자/독자 중심의 라이팅을 강조하고 있습니다(이 정도면 강요라고 해도 될 것 같네요^^).
modified — “documentation” has been replaced by “information for users” (…) “engineering, business professionals” has been added.
아예 대놓고 ‘기술 문서’라는 딱딱하고 작성자(개발자) 중심의 표현도 지양하라고 합니다.
다양한 목적과 동기를 가진 문서 독자를 위한 ‘정보’ 정도로 일축해버립니다.
‘문서(서류)’ 대신 ‘(다양한) 사용자를 위한 정보’라는 더 broad한 표현을 사용하자고 권고합니다.
ISO의 강한 의지를 개정판 전체에서 느낄 수 있었습니다.
아마 익숙한 교과서적 인사이트를 전달한다는 느낌을 피하고 싶은 것처럼 보였습니다. 정신 차리고, 지금까지의 문서화에 대한 정의를 의심하고 바꿔보고, 모두를 위해 개선하라는 ISO의 선언으로 받아들였습니다.
기술 문서가 제공하는 ‘정보, 구조, 내용 등’을 결정하는 주체가 바로 ‘사용자’라고 강조합니다.
기술 문서의 ‘주인’은 작성자 집단이 아니라 다양한 Audience라고 강조합니다. 이 정도면 기술 문서를 작성하는 많은 라이터들이 섭섭해할지도 모르겠습니다(저는 아닙니다).
API 및 챗봇은 2022 개정판 주요 개정 사항입니다.
API를 새롭게 강조하는가 싶어 눈을 크게 뜨고 문서를 따라가니, 이 역시 ‘사용자’ 중심으로 작성하라는 권고입니다.
과거엔 “information for use”라고 표현했지만, 이제는 “information for users”로 표현하겠다고 호언합니다. 재밌죠?
기술 문서에 들어가는 많은 이미지, Figure, 표, 차트 등도 ‘사용자 중심’의 결과물이 되어야 한다고 재차 반복합니다.
이런 걸 ‘스타일’이라고 부르는 게 아닐까요.
제 결론입니다.
2022년 개정판에서 ISO/IEC/IEEE 26514는 (앞으로) 한층 더 사용자 중심의 소프트웨어 개발 문서를 제작하도록 권고하겠다고 으름장을 내놓았습니다.
골똘히 생각하거나 멀리서 찾을 필요가 없습니다.
우리가 만들어온 ‘기술 문서’는 이만큼 왔습니다.
이제 ISO/IEC/IEEE 26514를 보고도 겁먹지 않을 정도로 몸을 풀었다면 우리 앞에 놓인 도마 위의 생선을 봅시다.
우리는 아래의 리스트를 통해 하나의 근본 전략을 세울 수 있습니다.
Technical Documentation 프로세스의 최 앞단으로 돌아가서 라이터는 자신에게 질문해봅시다.
A. 개발자가 읽기 편한 문서
B. 사용자가 읽기 편한 문서
“이 문서는 누구를 위한 문서인가? 비율로 나눈다면 몇 대 몇이 될 것인가?
위 두 방향은 linear한 대척점에 있는가? 그렇지 않을 것이다.”
다행히 우리는 위에서 ISO/IEC/IEEE 26514를 통해 방향 정도는 확실히 알고 있습니다.
갈림길에서 헤맬 필요가 없습니다. 시간 낭비하지 않아도 됩니다.
“B가 강조되고 있으며
B가 A를 포용하는 방향으로 가고 있다.”
문서를 가운데 두고 답을 도출하는 식으로 결론을 내려야 합니다.
“국제 표준은 사용자를 어떻게 정의하고 있는가? 우리는 사용자를 어떻게 정의하고 있는가?
우리 제품의 사용자는 누구인가? 이 기술 문서를 누가 사용하는가?”
실무자는 컨센서스를 리드해야 합니다. 저는 먼저, 우리가 싱크를 맞추고 합의했으면 좋겠습니다.
합의되지 않으면 글로벌 표준화를 위한 프로세스(시스템)를 설계할 수 없으니까요.
그러려면 글로벌 표준을 지키지 않았을 때 어떤 불이익과 불편을 감수해야 하는지부터 이해해야 합니다.
시장 규모와 시장에 대한 정의는 중요합니다.
특정 region만을 대상으로 제품을 개발하고 사업 활동을 영위하는 것은 글로벌이 아닙니다.
글로벌 마켓은 전 세계를 대상으로 합니다. 전 세계를 하나의 대상으로 정의하고(일원화) 그 대상이 가진 공통 분모를 표준화를 통해 효율적으로 관리합니다. 글로벌 마켓을 경험해본 조직과 그렇지 않은 조직 사이엔 상상하기 힘들 만큼의 효율성 차이가 있습니다.
표준화란 최적의 효율화 추구를 의미합니다. 효율 최적화만이 표준화 체계를 구성할 수 있으니까요.
글로벌은 표준화를 의미한다고 말씀드렸고, 자연스럽게 글로벌 마켓을 겨냥한 제품은 기술력을 갖춰야 한다는 결론을 얻습니다. 고객의 손을 놓지 않으려면(고객을 잃지 않으려면) 고객의 속도를 읽어야 합니다.
표준화되어 있지 않은 운영 프로세스는 보유 고객을 잃어버릴 가능성을 늘 안고 있으며 잠재 고객을 확보하기 어려울 것입니다. 데이터에 근거한 예측이 어려울 것이기 때문이죠.
속도를 갖춘 기술은 경쟁력이 됩니다. 속도를 갖추려면 준비되어 있어야 합니다. 속도에는 정확성이 담보되어야겠죠.
그렇다면 정확성은 어디에서 나올까요? ISO의 국제 표준만큼 정확한 연구 결과가 또 어디 있을까요. 심지어, 그 국제 표준을 글로벌 기업과 선진국이 오랫동안 팔로우하고 프로세스에 반영하며 개발해왔다고 한다면요.
앞서 말씀드린 ‘공기’와 같은 존재일 겁니다. 기술력(경쟁력)은 그 다음의 이야기일 수 있습니다.
결론입니다.
글로벌 표준에서 벗어난다면 세계 어느 나라에서도 통하지 못할 수 있습니다. Domestic도 마찬가지입니다.
소프트웨어 제품 문서(기술 문서)의 방향은 정해져 있다고 볼 수 있습니다. 사용자 경험과 사용자 다양성을 고려한 Humanized 라이팅을 하나의 전략으로 삼을 수 있습니다.
아래의 책이 떠오르는 건 왜일까요?
무거울 줄만 알았던 국제 표준에 대해서 간략히 알아봤고, 소프트웨어 기술 문서가 가야 할 방향도 체크했다면.
자, 이제 우리 앞에 놓인 생선을 파헤쳐봅시다.
비교는 나쁘지만 그래도 글로벌 플레이어들이 어떻게 자사의 기술 문서에 ISO/IEC/IEEE 26514
를 적용하고 있는지 아는 것은 매우 중요합니다.
SaaS, PaaS, IaaS 클라우드 기반 서비스 선두 기업은 어떻게 기술 문서를 배포하고 있는지 살펴봤습니다.
쫄지 말자
엄마 친구 아드님과 친구 아들의 집은 이렇게 달랐습니다.
위에서 정리한 요점을 기반으로 TO-BE를 제안합니다(feat.ISO/IEC/IEEE 26514
).
대상: Kakao Login > Concepts / Prerequisites
카카오 기술 문서
는 다양한 레이어의 독자를 고려하기보다 개발 정보과 카카오 연동 매뉴얼만을 빠르게 수집하고자 하는 독자에게 최적화된 톤앤매너 및 형태로 보입니다.카카오 로그인
기술 문서는 타사의 문서에 비해 조금 건조한 편이라고 보입니다. 카카오 로그인
이해와 설정 정보에 스토리텔링이 부여된다면 조금 더 부드럽고 친절하게 전달될 수 있을 것입니다.카카오 로그인
기술 문서에는 직관적인 튜토리얼과 CTA 장치들이 빈약합니다. 유저 플로우를 통해 작성되었다기보다 정보의 나열과 정렬에 집중해 단순하게 제작되었다고 보입니다.카카오 로그인
기술 문서는 depth가 적습니다. 서치바를 통해 빠르게 원하는 정보만을 얻기를 원하는 독자에겐 전혀 문제가 되지 않을 겁니다. 하지만 지나친 단순함은 다양한 독자에게 독이 될 수 있습니다. 예를 들어 지식이 많지 않거나 나이브한 사용자라면 지나치게 긴 페이지의 정보에 압도되어 사용 기능에 관한 기술과 소프트웨어 지식을 만날 기회 자체를 포기할 수도 있습니다.카카오 로그인
기술 문서까지 찾아온 독자라면 클릭 몇 번에 지치거나 이탈할 가능성은 적어 보입니다.카카오 로그인
기술 문서는 있어야 할 기본 정보들이 알맞은 포맷으로 자리하고 있습니다. 그러나 기술 문서 국제 표준 및 트렌드에 비춰볼 때, 다양한 포맷의 아웃풋을 통해 독자를 만나는 것도 비즈니스를 넓히는 데 중요한 요소로 보입니다. 기업의 모든 행동엔 비용이 뒤따르는 법인데 타사의 기술 문서엔 다양한 매체의 사용을 통한 콘텐츠 아웃풋이 도드라져 보였기 때문입니다.카카오 로그인
기술 문서는 조금 정적으로(static)으로 보이고, 타사의 문서는 다이나믹하고 역동적으로 느껴졌습니다. 확연한 차이가 있음을 느낄 수 있었습니다.기술 문서를 peer-review하고 사용성 평가하는 과정에 필요한 Check-list를 준비했습니다.
ISO/IEC 26514
는 제품 평가와 사용자 매뉴얼 품질 평가를 동시에 할 것을 제안합니다.
이는 소프트웨어 품질 평가가 매뉴얼을 읽으면서 동시에 진행되기 때문입니다.Software Document Standard
도입
- ISO/IEC는 ISO/IEC 9126과 14598을 바탕으로 SQuaRE(Software product Quality Requirement and Evaluation)란 소프트웨어 품질 평가 척도를 개발하고 ISO/IEC 25000을 공표함.
- 소프트웨어 문서 제작은
ISO/IEC/IEEE 2651N
시리즈에 근거해 진행해야 함.
그런데 이걸 꼭 해야 할까요?
바쁘면 좀 못 챙길 수도 있고, 생략할 수도 있고, 빠트릴 수도 있겠죠?이 단계가 당장 우선순위에 들지 못할 수 있으니까요.
— 엉엉…(국내 스타트업 개발팀에서 생존한 TW의 곡소리)
이걸 하는 목적과 필요성에 대한 설명은 생략하겠습니다.
이 전략과 실천이 왜 필요하다고 했죠? 하지 않으면 안 되니까 하고 있다고 말씀드렸습니다.
이는 Global Standard라는 목적지로 가는 여정 중 하나일 뿐이며 이 단계(기술 문서 평가 체크 리스트) 역시 글로벌 표준을 따릅니다.
따라오시죠.
제가 준비한 카카오 기술 문서
평가 Check-list를 함께 봅시다.
Ref.
Technical Writing과 기술 번역 10기, 최형선TW, 한겨레교육
테크니컬 라이팅 4대 원칙 by kakaoenterprise
https://tech.kakaoenterprise.com/102
개발자들을 위한 테크니컬 라이팅 10계명 by kakaoenterprise
https://tech.kakaoenterprise.com/110
기술 문서 품질 고도화 프로젝트는 많은 문서 이해관계자(stakeholder)를 필요로 합니다.
어느 시기에 어느 정도를 스콥으로 잡아갈지에 따라 프로젝트 전략과 볼륨이 달라질 것으로 보입니다.
Check-list 역시 테크니컬 라이팅을 목표로 모인 동료들과 싱크를 맞춰 준비해야 하고, 단계에 맞게 적절히 수정되어야 할 것입니다.
이상입니다.
이렇게 해서 소프트웨어 제품과 제품 문서에 대한 국제 표준부터 글로벌 기업의 선진 사례를 알아보고, 저희의 기술 문서에 대한 수정 제안을 살펴보는 시간을 가졌습니다.
긴 글 읽어주셔서 감사합니다.
Published by Technical writer, Janghyun lee