Robert's Rules of Order for API Documentation Writing이라는 문서에 대한 번역입니다. 개인적인 학습 용도이며, 아마도 이 글을 보는 것보다 이 글을 작성한 시점보다 좀 더 나아진 기계번역의 힘을 빌리는 것이 좀 더 좋은 방법이라 생각됩니다.
https://writeonce.org/roberts_rules_of_order.php
참고로 원문 제목에서 Robert's Rules of Order이라는 것은 미국 내에서 사용하는 회의 규칙 같은 것이라고 하는데요. 아마 글쓴이는 이를 패러디한 것이 아닌가 싶네요. 이걸 알면 괜찮은데 그대로 직역하면 좀 어색한 표현이 되어서 그냥 가이드라인 정도로 번역했습니다.
(참고: https://en.wikipedia.org/wiki/Robert%27s_Rules_of_Order)
WTD 2024 포틀랜드 강연에서 언급한 가이드라인인데 미디엄에 작성한 것이 있고 본인 사이트에 작성한 것이 있습니다.
https://medium.com/codex/roberts-rules-of-order-for-api-documentation-writing-a2d52bfba41c
미디엄에 작성된 것이 좀 더 항목이 많은데 “To see the complete story, visit Roberts_Rules_of_Order. To see more, visit my site WriteOnce.org.”라고 되어 있어서 여기 내용은 그의 사이트에 있는 내용을 번역했습니다.
WTD 2024 포틀랜드 강연은 아래 링크를 참고해주세요.
2024.05.29 - [테크니컬 라이팅/WTD 컨퍼런스] - WTD 포틀랜드 2024 - OpenAPI 도입 가이드: 테크니컬 라이터를 위한 4단계
다음은 API 문서 작성을 위한 일련의 지침입니다. API 문서 작성은 동료들로부터 존경과 찬사를 받을 만한 흥미로운 분야입니다. 하지만 애플리케이션에 문제가 발생하지 않는다면 별로 주목받지는 못합니다. 뭔가 문제가 생겨야 관심을 가지기 시작하죠.
많은 사람들이 API 문서는 설계 문서를 기계적으로 옮겨 적는 정도로 여기고 자동으로 생성되는 문서만으로 충분하다고 생각합니다. 하지만 그렇지 않습니다. 자동으로 문서를 생성하는 코드나 리소스를 만드는 것은 누구일까요? 여기에는 창의적인 노력이 있습니다. 많은 경우 처음 테크니컬 라이터로 일하는 이들은 글쓰기 기술만 배우고 왜 글을 쓰는 것인지 잊어버립니다. 테크니컬 라이팅의 핵심은 정보를 전달하는 것입니다. API 문서 작성을 시작할 때 독자의 기대에 부응하는 방법을 배우세요. 그럼 나머지는 저절로 따라올 겁니다. 이제 설명할 내용은 로버트의 API 문서 작성 지침이라고 합니다. 아니면 로버티즘(Robertisms)이라고 해도 괜찮습니다.
1. 누구나 초보자가 될 수 있습니다
API 가이드 문서는 초보자 또는 처음 해당 기술을 접하는 이들을 위해 준비되어야 합니다. 많은 이들이 API를 사용하려는 사람들은 기초 자료를 건너뛸 수 있을 만큼 충분한 기술을 가지고 있을 것이라 생각합니다. 하지만 그렇지 않습니다. 기술에 익숙한 이들만을 위한 문서를 만들어서는 안 됩니다. 모든 사람이 모든 것을 알지 못할 만큼 많은 종류의 프로그래밍이 있습니다. 예를 들어 C#이나 Java에 능숙한 개발자도 npm을 모를 수 있습니다.
2. 나를 위한 문서를 작성하세요
여러분 자신에게 설명하는 문서를 작성하세요. 업무를 진행하기 위한 참조 가이드라 생각하고 수준에 맞게 세부 정보를 포함하세요. 예를 들어 3~6개월에 한 번만 실행하는 업무라고 생각해 보세요. 3개월이 지나면 기본적인 절차는 기억하겠지만 세부 절차는 거의 잊어버리게 됩니다. 가장 중요한 것은 작은 세부 절차입니다. 6개월이 지나면 어디서 업무를 시작하는 건지도 기억하지 못할 겁니다. 뭐가 뭔지 알 수 없고 어떻게 해야 하는지도 모르고 도움을 줄 만한 개발자가 항상 같이 있는 것도 아니라는 것을 생각한다면 지금 당장 문서화가 필요합니다. 여러분이 겪는 문제는 다른 동료들도 마찬가지로 겪을 수 있습니다. 지금 당장 문서화를 시작하세요. 일정을 조정하거나 모르는 내용을 문서화하는 것을 두려워하지 마세요.
3. 처음을 기억하세요
대부분의 사람들은 어떤 일을 처음으로 한 번만 합니다. 우리는 매일 처음으로 뭔가 하는 경험을 하게 됩니다. API 문서 작성자는 처음으로 뭔가 하는 것에 대해 설명하는 방법을 배워야 합니다. 어떤 문제가 발생했는지, 무엇이 여러분을 좌절시켰는지, 그리고 문제를 어떻게 해결했는지 기억하세요.
4. API 문서는 모든 이들을 위한 것이어야 합니다
초보자와 경험이 풍부한 개발자 모두 같은 문서를 읽습니다. 그렇다고 해서 모든 문서를 초보자와 경험이 풍부한 개발자를 고려해 작성해야 한다는 것은 아닙니다. 물론 한쪽에만 편중해서도 안됩니다. 하지만 어느 시점에서 숙련된 개발자에게 초점을 맞추게 됩니다. 이것은 자연스러운 현상입니다. 문서 작성자가 제품에 익숙해지면서 이런 것은 다 알고 있을 것이라 가정하게 됩니다. 이런 순간 문제가 발생할 수 있습니다. 잊지 마세요. 여러분의 제품을 처음 접하는 사람들을 생각하고 여러분이 시작하면서 겪었던 문제를 기억하세요. 모든 것을 문서화하세요.
5. 개발자의 게으름에 호소하세요
개발자에게 인정받으려면 감정에 호소해야 합니다. 그들에게 감탄하거나 존경하라는 것이 아닙니다. 게으름에 호소하라는 겁니다. 개발자는 본질적으로 게으릅니다. 그들은 일을 한 번만 하는 것을 좋아합니다. 그들의 시간을 절약할 수 있게 해 주세요. 복사해서 사용할 수 있는 코드를 제공하는 것도 하나의 방법입니다. 페이지에 표시되는 내용이 짧을수록 여러분을 더 좋아하게 될 겁니다. 공통으로 참조하는 리소스를 바로 볼 수 있게 배치하면 아래로 스크롤할 필요가 없습니다. API 참조 가이드는 단순한 지침이 아니라 코드 저장소라는 점을 이해하세요. 충분히 좋은 코드 샘플을 만드세요. 그럼 개발자들이 코드를 기억할 필요 없이 복사해서 사용하기 위해 문서를 찾을 겁니다.
6. 단계별 지침을 사용하세요
레퍼런스 가이드뿐 아니라 모든 문서에서 단계별 지침을 사용하세요.
7. 어떤 것을 알고 있는지 이해하세요
가장 중요한 규칙입니다. 여러분이 어떤 것을 알고 있는지 이해해야 합니다. 그렇지 않으면 독자도 이것을 알고 있을 것이라 가정하고 문서를 작성할 수 있습니다. 사람들은 새로운 공예, 취미, 직업을 가지게 되면 시간을 보내면서 자연스럽게 전문적인 용어와 개념에 익숙해지게 됩니다. 그러면서 전문가가 되는 것이죠. 전문적인 용어를 사용하면 이미 알고 있는 개념을 다시 설명하는 노력을 덜 수 있습니다. 특정 주제에 능통한 이들 역시 용어나 개념을 잘 이해하고 있습니다. 그렇기 때문에 효과적으로 의사소통이 가능하죠. 이들은 같은 비밀 해독기를 가지고 있는 것과 같습니다. 문제는 해당 기술을 잘 모르는 이들이 정보를 얻어야 하는 경우입니다. 테크니컬 라이터가 필요한 이유이기도 하죠. 이들은 전문적인 용어를 거의 이해하지 못합니다. 특히 약어의 경우 더 어렵습니다. 전문적인 용어를 사용하는 것이 나쁜 것은 아닙니다. 우리는 그런 용어나 개념을 정의했는지 확인하기만 하면 됩니다.
공포 영화 속에서 탈출한 피해자가 작은 마을 보안관을 만나서 외계인, 광선총과 같은 말을 마구 이야기하는 장면을 생각해 보세요. 여러분은 이미 영화 속에서 피해자가 어떤 경험을 했는지 보았기 때문에 어떤 말인지 잘 알고 있습니다. 하지만 작은 마을의 보안관은 이 상황을 전혀 이해하지 못합니다. 그가 이해할 수 있는 맥락이 필요합니다. 테크니컬 라이터도 다음에 어떻게 진행되어야 할지 알고 있다는 이유만으로 중요한 정보나 단계를 생략하는 경우가 너무 많습니다. 절차를 검토할 때 실제 수행 중인 단계를 확인하고 중요하지 않은 단계라 판단하고 제외한 것은 아닌지 확인하세요. 이런 단계도 문서화에 포함되어야 합니다.
8. 어떤 것을 모르고 있는지 이해하세요
7번 어떤 것을 알고 있는지 이해하세요의 반대입니다. 여러분이 모르는 것을 독자가 알고 있을 수도 있습니다. 예를 들어 날씨 API를 읽고 있는데 여러분이 모르는 용어가 포함됐을 수 있습니다. 아마도 다른 독자들은 알고 있는 용어이고 내용을 이해할 수 있었을 겁니다. 하지만 여러분처럼 용어를 이해하지 못한 독자도 있을 겁니다. 이런 문서는 문제가 있는 거죠. 하지만 문서를 작성하는 여러분은 이런 상황을 이해해야 합니다. 여러분이 잘 모르는 기술에 대한 문서를 작성해야 할 수도 있습니다. 잘 모르는 기술에 대한 용어는 충분히 이해하고 있어야 합니다.
9. 독자들이 모르는 것을 이해하세요
이것은 두 번째로 중요한 규칙입니다. 독자가 무엇을 모르거나 알지 못할지 이해한 다음 해당 정보를 문서에 포함해야 합니다. 테크니컬 라이터가 내용을 잘 알고 있는 경우 이 단계를 간과하기 쉽습니다. 앞에서 언급한 규칙들을 다시 살펴보세요. 누구나 초보자가 될 수 있습니다. 나를 위한 문서를 작성하세요. 처음을 기억하세요. 그러면 어떤 것을 포함해야 하는지 이해할 수 있을 겁니다.
10. 관리자가 항상 옳은 것은 아닙니다
API 문서 작성자나 팀을 제대로 이끌어본 관리자는 거의 없습니다. 제한된 프로그래밍과 API 경험을 바탕으로 API 문서 작성자의 의견은 무시하고 결정을 내립니다. 그래서 API 문서 프로젝트를 기술 문서 작성 프로젝트와 같은 식으로 취급합니다. 이렇게 해서 얻은 결과는 좋지 않습니다. 하지만 관리자에게 기술 문서 작성 프로젝트처럼 다루어서 실패한 것이라고 설득하기는 쉽지 않습니다. 하지만 여러분은 단지 지시를 받기 위해 있는 것이 아니며 여러분의 경험과 통찰력을 제공해야 한다는 말을 어디선가 읽은 적이 있습니다. API 문서 작성자는 관리자의 업무 역량이나 판단력이 잘못된 방향으로 가지 않게 도움을 주어야 합니다. 관리자의 의견을 그냥 따르기만 한다면 여러분에 대한 신뢰를 저버리는 것입니다.
11. 모든 용어를 정의하세요
일부 용어, 대부분의 용어, 많은 용어가 아니라 모든 용어를 정의하세요. 문서란 무엇인지도 포함되어야 합니다. 적당히가 아니라 모든 용어가 대상입니다. 유사한 두 항목의 차이를 정의합니다. 두 항목을 구별해야 할 경우 이에 대한 용어가 필요합니다. 손목에 차는 시계를 최초로 만든 사람은 손목시계(Wristwatch)라는 새로운 용어를 만들 권리를 가지게 됩니다. 그전에도 시간을 측정하는 장치가 있었지만 이제는 이를 설명하기 위한 좀 더 정확한 용어가 필요하게 됐습니다. 개념을 정확하게 설명하는 용어를 선택하고 해당 용어를 일관되게 사용하세요. 용어를 정의한다는 것은 해당 정보와 관련 맥락을 배우고 그에 대한 지식을 가지고 말할 수 있는 것을 의미합니다. 용어를 정의하면 해당 용어를 가질 수 있게 됩니다.
12. 일반적이고 모호한 개념
API에서 개념 정보는 공통 개념과 모호한 개념 2가지로 구분할 수 있습니다. 공통 개념은 사용자, 독자가 이미 알고 있을 가능성이 높은 개념입니다. 하지만 어딘가에는 정의가 되어 있어야 합니다. 공통 개념에 대한 콘텐츠에는 따로 긴 설명이 필요하지 않습니다.
모호한 개념은 사용자, 독자가 모를 수 있는 개념입니다. 덜 대중적인 개념일 수도 있고 제품 고유의 개념일 수도 있습니다. 모호한 개념이 포함된 콘텐츠일 경우 개념에 대한 정의와 함께 2-3줄 정도 설명이 포함되는 것이 좋습니다. 개념 설명을 빠뜨리거나 링크로만 추가하거나 다른 곳을 참고하라고 언급하지 마세요. 해당 개념을 사용하는 이유와 어떤 식으로 사용하는지 예시를 추가하세요. 재사용 가능한 콘텐츠뿐 아니라 모든 콘텐츠에 해당하는 지침입니다. 최소한의 작업으로 사용자가 혼란에 빠지지 않게 도울 수 있습니다.
간단한 예로 아래 그림은 마이크로소프트 워드의 글꼴 대화 상자입니다. 한 항목을 제외하면 모든 항목을 이해할 수 있습니다. 하지만 문자 높이 일치(Equlize Character Height)는 바로 어떤 개념인지 떠오르지 않습니다. 이런 것을 모호한 개념이라고 할 수 있습니다. 다른 항목은 설명을 추가하지 않아도 이런 항목은 설명이 필요합니다.
* 문자 높이 일치 기능은 영어처럼 글자의 높이가 다를 때 강제적으로 높이를 맞추어 주는 기능입니다. 예를 들어 Test라고 쓴 경우 T 글자 높이에 맞추어 나머지 est 글자의 높이를 강제로 늘려주는 것입니다.
13. 우리는 그들의 편의를 위해 여기에 있습니다
여기서 “그들”은 제품 사용자입니다. 여러분이 힘들더라도 그들을 위해 가능한 많은 일을 하세요. 우리는 가능한 제품을 편리하게 이용할 수 있게 해 그들이 좋은 경험을 할 수 있게 돕습니다. 에러 핸들링, 타입 체크 같은 것을 포함하는 코드 샘플을 작성해 주는 것을 의미합니다. 필요한 리소스(enums, 오브젝트, 반환값 등)를 바로 확인할 수 있게 링크를 추가해 주세요. “문서를 참고하세요”라고 뭉뚱그려 연결하지는 마세요.
14. 우리는 그들의 편의를 위해 여기에 있습니다
여기서 “그들”은 조직 내 개발자입니다. 여러분이 힘들더라도 그들을 위해 가능한 많은 일을 하세요. 질문을 하기 전에 직접 코드 샘플을 작성해 보고 관련 자료를 참고하세요. 그들의 시간을 빼앗지 않도록 주의하세요. 그렇지 않으면 그들에게 번거로운 짐이 될 수 있습니다.
15. 이것은 코드입니다. 다른 게 아니라구요
API는 모두 코드에 관한 것입니다. 따라서 가능한 많은 코드, 예제, 스니펫을 포함하는 것이 당연합니다. 모든 호출에 대한 코드 예제가 있어야 합니다. 또한 전문 용어, 기술적인 용어 심지어는 유머 코드도 알아야 합니다. 프로그래머와 대화하려면 프로그래밍에 대해 최대한 많이 알아야 합니다. 그렇지 않으면 그들이 여러분의 문서에서 잘못된 용어를 찾아낼 것이고 여러분은 지식에 대한 신뢰를 잃게 될 것입니다.
16. 예제가 전부입니다
이것은 과정이 아닙니다. 코드 샘플만 사용해서 API 참조 가이드를 작성해도 된다면 그렇게 했을 겁니다. 각 호출마다 하나 이상의 코드 샘플이 있어야 합니다. 여러 코드 샘플이 있을 수도 있습니다. 예를 들어 호출에 대한 설명에서 간단한 코드 예제를 복사해 붙여 넣어서 바로 실행할 수 있어야 합니다. 나중에 매개변수 값을 사용자에 맞게 수정해서 변경하도록 합니다. 그런 다음 해당 호출에 대한 포괄적인(각 옵션에 대한 실행 예시를 포함한) 샘플을 제공하세요. 마지막에서는 해당 호출을 사용하지만 더 큰 맥락에서 문제를 해결하는 실제 사례를 포함하세요. MSDN에서 제가 가장 좋아하는 페이지는 드래그 앤 드롭 프로그래밍을 설명하는 페이지입니다. 드래그 앤 드롭은 동시에 두 가지 메커니즘이 작동해야 한다는 점에서 쉽지 않았고 처음부터 코드를 작성하는 경우 이를 디버깅하기 쉽지 않았습니다.
이 페이지에서 내가 본 것은 가장 완벽한 예제 중 하나였습니다. 코드를 거의 변경하지 않고도 프로젝트에 복사해 붙여 넣을 수 있으며 바로 컴파일할 수 있었습니다. 나는 그 페이지를 북마크로 저장하고 드래그 앤 드롭이 필요할 때마다 참고했습니다. 너무나도 간단해서 자꾸 사용해보고 싶을 정도였습니다. 이것은 좋은 예제에 대한 좋은 예제입니다. 프로그래머가 참조 자료가 아닌 코드 샘플에 대한 문서를 다시 볼 수 있게 하세요. 불행하게도 정말 좋은 샘플이었는데 마이크로소프트에서는 이 페이지를 제거했습니다. 다행인지 개인적으로 그 페이지를 따로 저장해 놓았습니다.
17. 여러분의 글쓰기는 결코 끝나지 않습니다
수정하고 수정하고 수정하세요. 항상 문서를 검토하세요. 항상, 영원히, 더 많이 검토할수록 더 좋아질 겁니다. 먼저 문법적인 오류를 찾습니다. 그리고 어제보다 더 많은 것을 오늘 알게 되었으니 자료를 추가하고 업데이트하고 수정하세요. 3개월이 지나면 다시 관련 자료를 살펴보세요. 그때쯤이면 프로그래머에게 중요하지만 사소한 세부 사항에 대해서는 거의 잊어버렸을 겁니다. 나머지도 잊어버리는데 그리 오랜 시간이 걸리지 않습니다. 그래도 괜찮습니다. 마음을 잡고 코드를 다시 수정해 보는 것은 아무런 문제가 없습니다.
18. 끊임없이 검토하세요
글쓰기와 마찬가지로 끊임없이 검토하는 것이 필요합니다. 글을 쓰고 나서 며칠, 몇 주, 몇 달 후에 다시 돌아가 보세요. 그렇지 않더라도 해당 문서를 다시 읽을 때마다 검토해 볼 수 있습니다. 문서 내 버그는 교활하며 시간을 들인 만큼 더 많은 버그를 찾아낼 수 있습니다. 문장을 다시 작성해 보세요. 여러분의 상사는 그럴 시간이 어디 있냐고 질책할 수도 있지만 무시하세요. 기회가 있을 때마다 문서를 더 좋게 만드세요.
19. 우리는 개발자의 옹호자가 아니라 사용자의 옹호자입니다
여러분은 회사에서 급여를 받지만 사용자를 위해 일합니다. API 문서 작성자는 사용자를 옹호하는 독특한 위치에 있습니다. 우리는 개발자, UX팀, PM이 가지고 있지 않은 외부자의 시선을 가질 수 있습니다. 예를 들어 개발자는 코드에 너무 가까이 있고 집중하기 때문에 사용자의 문제를 제대로 볼 수 없습니다. API를 문서화할 때 이해되지 않거나 불명확하며 변경이 필요하다고 생각되는 사항이 있다면 이슈로 등록해서 수정하세요. 예를 들어 저는 모든 API가 대소문자를 구분할지 여부를 사용자가 설정할 수 있게 이슈를 등록했습니다. 프로그래머가 항상 챙기지는 않는 부분이며 이 때문에 사용자가 어려움이 처할 수 있습니다. 또 다른 예는 오류 메시지입니다. 메시지는 오류, 유형, 발생 위치를 포함해야 하며 다음에 수행할 작업에 대한 제안을 제공해 사용자가 명확하게 이해할 수 있어야 합니다.
20. 아직 깨지지 않았다면 깨뜨려 보세요
일반적으로 테크니컬 라이터, 특히 API 문서 작성자들은 부당한 대우를 받는 그룹이며, 우리가 필요로 하는 도구를 받지 못하고 있습니다. 이는 우리에게 필요한 도구를 주지 않는다면, 우리가 그것들을 요구해야 한다는 것을 의미합니다. 따라서, 도구를 만드는 회사들에게 끊임없이 불평하며 버그를 수정하도록 요청하고, 우리의 필요에 맞는 변경을 제안해야 합니다. 우리는 현재의 도구를 거부하고, 우리의 가장 독특한 요구에 맞는 새로운 것들을 만들 것을 기대해야 합니다. 만약 그들이 그렇게 하지 않는다면, 우리 커뮤니티가 나서서 새로운 것들을 만들어야 합니다. 우리가 현재 상태를 유지하거나 부족한 도구들을 가지고 일해야 할 이유는 없습니다.
21. 스스로 마음에 들지 않으면 잘못된 것입니다
API 문서 작성자는 API 문서 작성의 전문가입니다. 잘못된 부분은 바로잡을 것으로 예상됩니다. 그러므로 뭔가 마음에 들지 않는다면 바꿔야 합니다.
22. 모두가 여러분을 위해 일합니다
여러분은 정보가 필요하고 그들은 정보를 가지고 있습니다. 여러분은 그들에게서 정보를 얻을 것입니다. 필요한 정보를 요청하는 것을 두려워하지 마세요. 특히 다른 조직에 있는 경우에 더욱 그렇습니다. 공식적인 커뮤니케이션 라인에 대해 걱정하지 마세요. 물론, 너무 무례하게 해서는 안되고 모두가 바쁘다는 것은 인정해야 합니다. 그렇지만 자유롭게 정보를 요청하세요. 이를 통해 여러분의 네트워크가 넓어지고, 다양한 관점을 갖게 되며, 더 많은 사람들을 새로 만날 수 있습니다. 가만히 있으면 정보를 얻지 못합니다.
23. 여러분은 개발자에게 짜증 나는 존재일 수 있습니다
놀랍지만 사실입니다. 테크니컬 라이터는 때때로 개발자에게 짜증 나는 존재입니다. 개발자는 하던 일을 멈추고 시간을 들여 여러분을 이해시키기 위해 설명해야 합니다. 또 간단히 작성할 수 있는 코드도 검토해야 합니다. 하지만 이런 것들은 충분히 예상할 수 있는 일입니다(https://www.youtube.com/watch?v=T3dDRnTults). 개발자들은 A를 기대합니다. 여러분은 B를 기대하구요. 그리고 여러분은 개발자들이 C를 기대한다고 기대합니다. 이것은 모두가 겪어야 하고, 모두가 이해하는 평범한 불편함입니다.
여러분이 점수를 잃게 되는 부분은 여러분이 알고 있어야 하는 것을 질문할 때입니다. 먼저 공부를 하세요. 컴파일러에서 코드를 다루어보고, 구글에 검색하고, 주니어 개발자들과 이야기해 본 후에 질문을 하세요. 개발자의 시간을 절약해주어야 합니다. 코드 샘플을 작성하고 예외 목록을 작성하는 것처럼 복잡한 문제를 정리해서 핵심적인 질문을 할 수 있도록 하세요.
* 링크 영상의 내용은 애니메이션 심슨 가족의 일부입니다. 아들이 부엌일을 돕는다고 나서는데 제대로 하는 것이 없어서 오히려 엄마에게 방해가 된다는 뭐 그런 내용입니다.
24. 운이 좋다면 99% 실패할 겁니다
항상 새로운 아이디어를 시도해 보세요. 운이 좋다면 99%는 실패할 겁니다. 하지만 결국에는 쓸모 있는 아이디어를 얻게 될 겁니다. 그리고 어쩌면 원래 아이디어가 아니라 그 아이디어에서 파생된 아이디어일 수도 있습니다. 이것이 아이디어의 본질입니다. 기존 관습을 유지하려는 이들은 100% 실패합니다. 두 가지 아이디어를 시도했는데 그 아이디어가 모두 실패한다면 그들은 100% 실패하게 되고 아무런 성과가 없습니다. 하지만 100가지 아이디어를 시도하고 하나가 성공하면 99%의 실패율로 성과를 낼 수 있습니다. 물론 100개 중 하나가 성공하는 것도 운이 좋은 건데 결국 여러분이 원하는 것을 찾을 수 있습니다.
25. 어떤 과정도 복잡하게 만들 수 있는 만큼 단순한 과정은 없습니다
그렇게 하지 마세요. 우리는 일을 복잡하게 만들어서 자신을 부풀리는 것이 아니라 단순하게 만들어서 가치를 만들어냅니다. 여기서는 마키아벨리 같은 교묘한 술책을 쓰지 마세요.
* 마키아벨리(Niccolò Machiavelli)는 이탈리아 르네상스 시대의 정치 사상가로, 그의 저서 《군주론》(The Prince)에서 권모술수와 정치적 책략을 강조했는데 "마키아벨리적"이라는 표현은 종종 교묘하고 복잡한 전략이나 속임수를 의미한다고 합니다.
26. 테크니컬 라이팅에서 무엇을 의미하는지 추측하게 하지 마세요
명확하고 분명하게 작성하세요. 둘 다 아니라면 다시 작성하세요.
27. 유사한 항목은 유사한 동작을 가져야 합니다
일관성이 중요합니다. 두 개의 항목이 유사하면 유사하게 작동하고 문서에서도 유사하게 작성되어야 합니다. 예를 들어 toogle flag 매개변수를 설명할 때는 “항목을 다운로드할 수 있는지 여부를 나타냅니다”처럼 작성하고 true이면 ~, false이면 ~ 이런 식으로 작성해야 하는데 다른 항목에서 “예 - 다운로드할 수 있습니다. 아니요 - 사용자가 파일을 복사할 수 없습니다”라고 작성하면 안 된다는 이야기입니다. 두 번째 예시에서 잘못된 부분을 찾아보세요.
28. 중복은 의미를 명확하게 합니다
텍스트를 반복하면 사용자에게 정보를 명확하게 해 줍니다. 문서를 중복해서 작성하라는 것은 아닙니다. 버튼 이름, 버튼 선택 시 표시되는 대화 상자, 대화 상자의 텍스트 설명이 같은 제목으로 작성되어야 하고 같은 목적을 가지고 동작해야 한다는 것입니다.
29. 약어를 명확하게 표시하세요
약어는 사용하지 마세요. 그냥 사용하지 마세요. 약어 일부는 너무 명확해서 설명이 필요하지 않은 것처럼 보이기 때문에 다루기 어렵습니다. 하지만 실제 누구나 아는 경우는 매우 드뭅니다. 즉, 대부분의 독자는 그것이 무엇인지 모를 수 있고, 특히 제품에 고유한 것이라면 더욱 그렇습니다. 예를 들어 제어 센터 iOS 페이지는 MDM을 참조합니다.라는 설명에서 MDM이 뭔지 알 수 있나요? 무슨 뜻인지 아는 사람이 거의 없습니다.
1) 항상 모든 경우 정확한 명칭을 사용하세요.
2) 페이지의 첫 번째 항목에만 정확한 명칭을 사용하는 것을 고려하지 마세요.
API 참조 가이드를 사용하는 이들은 가이드의 어느 부분부터 읽기 시작할지 예측할 수 없습니다. 그들은 수많은 매개변수 중 특정한 매개변수 설명을 참조하기 위해 문서를 찾습니다. 문서 검색, 인터넷 검색, 링크 등을 통해 해당 페이지에 도달합니다. 요점은 페이지 상단부터 아래로 순차적으로 읽지 않는다는 점입니다. API 참조 가이드 상단에만 정확한 명칭이 있는 것은 아무 의미가 없습니다. 일반적인 테크니컬 라이팅과 API 문서 작성의 차이이기도 합니다. 중요한 것은 독자들이 약어가 무엇을 의미하는지 “당연히 알 것”이라고 이야기하는 사람이 있다면 꼭 혼내주세요.
30. 부끄러워하거나 점잖은 척하지 마세요. 어느 쪽이든 작업이 지연될 뿐입니다
가능한 모든 방법으로 정보를 얻으세요. 누구에게다 무엇이든 물어보고, 탐색해 보고, 가능한 모든 곳을 살펴보는 것을 부끄러워하지 마세요. “잘 모른다”라고 말한다고 해서 품위가 없는 것은 아닙니다. 일부 작가는 모든 분야의 전문가로 보이기를 원하며 아무것도 새롭게 배울 필요가 없다고 합니다. 하지만 우리는 그렇지 않으며 그래서도 안됩니다. 전문가들의 관점을 여러분에게 알려주도록 하세요. 그럼 좀 더 좋은 문서를 만들 수 있을 겁니다.
31. 독자는 여러분이 알고 있는 것을 정확하게 알 수 있어야 합니다
주어진 주제에 대해 여러분이 아는 모든 것은 문서화될 것입니다. 오류나 누락이 있다면 그것은 여러분이 글을 쓸 당시 주제에 대한 이해가 부족했다는 겁니다.
32. 우아한 변주는 필요 없습니다
우아한 변주는 독자가 지루하지 않게 시적 효과를 위해 같은 단어를 다른 단어로 바꾸는 것입니다. 로맨스 소설을 좋아하는 분들이라면 무슨 이야기인지 알 겁니다. 기술 문서는 용어를 아마추어처럼 사용해서는 안됩니다. 여러분은 소설을 쓰는 것이 아닙니다. 테크니컬 라이터는 달라야 합니다. 정확한 것을 의미하는 정확한 용어를 사용해야 합니다. 똑같은 것을 지칭하기 위해 매번 정확한 용어를 사용해야 합니다. 기억하세요. 모든 용어를 정의해야 합니다. 하나의 항목을 여러 방식으로 언급하지 마세요. 예를 들어 “문서를 폴더에 넣습니다. 나중에 디렉터리의 파일을 삭제하세요” 같은 문장입니다. 폴더/디렉터리, 문서/파일처럼 다른 용어를 사용해서는 안됩니다. 간단하죠. 하지만 많은 이들이 틀리는 부분입니다. 용어를 정의하고 반드시 일관되게 사용하세요.
* 재진술(再陳述, paraphrase, paraphrasing) 또는 어휘 변용(語彙變容) 등으로 표현되긴 하는데 한국어의 경우 영어만큼 이 부분의 중요성을 강조하지 않고 오히려 잘못 건드리면 가독성을 해치는 경우가 있어서 그냥 참고로만.
33. 기술 문서를 작성하고 있다는 것을 잊지 마세요
기술적인 개념과 절차를 소개하는 겁니다. 명시적으로 설명하세요. 정확한 용어를 사용하세요. 별칭이나 줄임말, 라틴어 같은 것을 사용하지 마세요. 완전한 내용을 작성하세요. 정확한 항목을 나열하고 ~등과 같은 표현은 사용하지 마세요. 잘못된 용어에 익숙해지면 나중에 고치기 어렵습니다.
34. 이론을 먼저 배우고 구현 세부 사항은 그다음입니다
요구사항을 준수하는 것이 품질의 정의라고 생각하고 테크니컬 라이터에게 요구사항 목록이 전달되는 경우가 너무 많습니다. 1985년의 필립 크로스비(Philip Crosby)가 그랬습니다. 채용 공고에서도 비슷한 경우를 볼 수 있습니다. 지원자는 Flare, DITA, REST, SOAP를 알아야 합니다. 이런 것을 아는 것은 좋은 일입니다. 하지만 독자의 기대를 이해하고 이를 충족하는 것이 좀 더 중요합니다. 그들이 원하는 정보가 무엇인지 어디서 정보를 찾게 할 것인지를 이해해야 합니다. 이것이 바로 API 문서 작성에서 도전받는 부분이고 흥미로운 점입니다. 그러고 나서 문서를 작성하는 것은 절차에 따라가는 것뿐입니다. 궁금한 것은 그때그때 찾아가면 됩니다.
* 필립 크로스비는 1985년 “Quality Without Tears”라는 책에서 "품질은 요구 사항을 충족하는 것(Quality is conformance to requirements)"이라는 개념을 제안했다고 합니다.
35. 마음의 평화
API 문서는 독자에게 자신이 하고 있는 일이 모든 단계에서 옳다는 확신을 주어야 합니다. 이것이 테크니컬 라이팅의 핵심입니다. 독자는 그것이 무엇을 의미하는지 추측할 필요가 없습니다. 마음의 평화는 독자에게 주어야 할 무형의 요소입니다. 이는 이메일에서 읽음 확인을 받는 것과 같으며, 대화할 때 고개를 끄덕이는 사람, 또는 아직 올바른 길을 가고 있음을 확인하는 도로 표지판과 같습니다.
36. 질문을 예상하세요
대부분의 문제에는 논리적인 질문이 자동으로 따라옵니다. 몇 가지 문제는 여러분이 문서를 검토하는 중에 발견할 수 있을 겁니다. 하지만 대부분의 문제는 명확하게 보일 겁니다. 아마 여러분이 궁금한 점이 있다면 독자도 마찬가지입니다. 따라서 이런 질문을 예상하고 문서 내에서 해결하세요. FAQ를 만들지 마세요. FAQ는 독자에게 번거로운 또 다른 장소일 뿐입니다. 문서 내에서 문제를 해결할 수 있게 하세요.
37. 독자들은 이미 알고 있는 내용은 무시합니다
문서는 모든 사람에게 필요한 모든 것을 담고 있어야 하지만 그렇다고 모든 것이 같아야 한다는 것은 아닙니다. 처음 제품을 접하는 독자를 위해 핵심 텍스트는 여전히 필요합니다. 그 후에 그들은 필요한 정보를 선별해서 선택할 것입니다. 아마도 특정 매개변수나 코드 예제일 겁니다. 정보가 너무 많으면 안 됩니다. 독자가 한 번만 읽었다고 해서 가치가 없다고 생각하지 마세요. 독자들은 필요하지 않은 정보는 알아서 건너뛸 것입니다. 여러분이 그들의 시간을 낭비하는 것은 아닙니다.
