8월 3일 요약 Sui AMA: 랜달 & 클레이와 함께하는 기술 글쓰기

Jen:
안녕하세요, 여러분. Sui AMA 시리즈의 다음 편에 오신 것을 환영합니다. 오늘은 사랑스러운 게스트인 Clay와 Randall과 함께 기술 문서 작성에 대한 자세한 내용을 논의해 보려고 합니다. 자기소개 부탁드립니다.

랜달:
안녕하세요, 제 이름은 랜달입니다. 제 나이를 알 수 있을 정도로 기술 문서 분야에서 오랫동안 일해 왔습니다. 사회학, 마케팅, 리서치, 통계학을 전공했지만 해당 분야에 취업할 수 없어서 컴퓨터 사용법을 독학으로 배웠습니다. 결국 시애틀로 이주하여 Microsoft에서 계약직으로 일하다가 테스터로 전환했습니다. 기술 문서 작성을 계속하게 된 계기는 사람들이 막힌 부분을 뚫고 문제를 해결하도록 돕는 것이 정말 즐겁다는 것을 알게 되었기 때문입니다. 제 사명은 훌륭한 문서를 만들어서 문서를 사용하는 사람들이 삶의 질을 높이고, 상사를 만족시키며, 직업적으로 더 성공할 수 있도록 하는 것입니다.

클레이:
저는 저널리스트로 시작했습니다. 이상주의자로서 그 일에 뛰어들었지만 실제로는 엄청나게 우울한 일이라는 것을 알게 되었습니다. 그 후 얼마 지나지 않아 홍보에 뛰어들었고 HTML을 접하게 되었는데 정말 재미있었어요. 기술 글쓰기에 빠져서 복잡한 구성 요소를 분해한 다음 사용법을 매끄럽게 설명하는 것이 정말 즐거웠어요. 정말 도전적이면서도 엄청난 보람을 느꼈습니다. 결국 저는 사람들이 자신의 이야기를 전달할 수 있는 도구를 만드는 데 도움을 줌으로써 사람들의 이야기를 전달하고 싶은 욕구를 확장하게 되었습니다.

. . .

질문 #1: 커뮤니티 회원은 어떻게 미스텐 프로젝트에 참여할 수 있나요?

클레이:
정말 마음에 듭니다! 랜달과 저는 모두가 문서를 검토하고 수정하는 데 도움을 주실 것을 강력히 권장합니다. 매우 간단하며, 지금 바로 할 수 있으며 GitHub 웹 편집기에서 편집하는 방법을 보여드릴 수 있습니다. 또한 사이트를 편집하고 기여하기에 더 매력적으로 보이게 할 수 있는 몇 가지 멋진 기능도 알려드릴 수 있습니다. 왼쪽 상단에 있는 docs.sui.io를 클릭하면 이제 개발자넷과 최신 빌드 버전을 모두 표시할 수 있습니다. 또한 각 페이지 하단에 내부 및 외부의 모든 기여자를 나열합니다. 그리고 하단에 소스 코드 링크를 제공하여 기본 마크다운 파일로 바로 이동할 수 있습니다.

저희는 엔지니어링과 함께 GitHub에서 직접 작업하므로 여러분의 기여는 Sui GitHub 프로젝트에 바로 반영됩니다.

. . .

질문 #2: 엔지니어링 팀에서 Notion이나 Google 문서 도구보다 Markdown을 선호하는 이유는 무엇인가요?

클레이:
멋진 질문이네요. 이상적인 상태라면 우리 모두 원하는 형식을 생성할 수 있는 편집기를 사용할 수 있을 것입니다. 엔지니어들은 이미 명령줄에서 작업하는 경우가 많으며, Vi와 같은 명령줄 편집기를 사용할 수도 있고, 랜달과 제가 현재 사용하고 있는 VS Code를 사용할 수도 있습니다. 이러한 편집기는 그래픽 기반이며, 기본적으로 HTML로 변환되는 일반 텍스트 인터페이스인 마크다운을 대량으로 편집하는 것이 훨씬 쉬워질 것입니다.

Randall:
네, 모두 동의합니다. 저희는 주로 마크독에서 작성하기 때문에 마크독을 선호합니다. GitHub 리포지토리에 Readme를 작성하는 경우 Markdoc에 작성합니다(저는 Markdoc이라는 독점적인 마크다운 구현이 있는 Stripe에서 왔기 때문에 Markdoc이라고 말합니다). 하지만 저는 사람들이 Markdoc에 피드백을 커밋해야 한다는 강박감이나 의무감을 느끼지 않도록 하고 싶습니다. Mysten의 테크니컬 라이터로서 제가 가진 목표 중 하나는 고도의 개발자가 되고자 하는 사람들이 우리 문서에 액세스할 수 있도록 하는 것입니다. 이전에 일했던 많은 곳에서 이러한 문제가 발생하는 것을 보았기 때문에 이를 바꾸고 싶었습니다.

따라서 문서에서 이해하지 못했거나 이해가 되지 않는 부분이 있다면 언제든지 알려주세요. 다른 사람에게는 이해가 되지 않을 수도 있고, 문구를 바꾸거나 추가적인 맥락을 추가할 수도 있습니다.

Jen:
제 경우에는 비기술적인 배경을 가지고 있기 때문에 멋진 지적이라고 생각합니다. 어쩌면 저자가 사람들이 이 글을 어떻게 해석하도록 의도했는지 제가 오해하고 있는 것일 수도 있습니다. 팀에 테크니컬 라이터가 있으면 많은 정보를 훨씬 더 접근하기 쉬운 방식으로 정리할 수 있기 때문에 큰 도움이 됩니다.

. . .

질문 #3: 업무에서 글쓰기와 편집이 차지하는 비중은 어느 정도인가요?

Randall:
그래서 사람들은 테크 라이터로서 우리가 하는 일에 대해 항상 오해를 합니다. 저는 실제로 콘텐츠를 만드는 데 20%, 편집하는 데 10%, 그리고 정보를 콘텐츠로 전환하는 데 60%의 시간을 보냅니다.

Clay:
엔지니어링에서 제출한 자료를 정리하는 데 상당한 시간을 할애하고 있으며, 내부 및 외부에서 변경 사항 검토 요청(풀 리퀘스트)을 많이 받다 보니 편집에 또 다른 시간을 할애하고 있습니다.

. . .

질문 #4: 수십 명의 엔지니어와 수천 명의 사용자의 요구를 충족하기 위해 어떻게 확장하고 있나요?

Randall:
때로는 창의적인 문제 해결을, 때로는 우선순위를 바꾸기도 합니다.
때로는 만나서 인터뷰를 하기도 하지만, 대부분은 무엇이 가장 영향력이 있고 무엇이 사용자에게 가장 도움이 될지 이해하는 것입니다. 때로는 충분한 문서를 작성한 다음 빠르게 팔로우하여 개선하거나 반복하기도 합니다. 사람들에게 더 많은 정보와 도움을 제공할 수 있을수록 이를 대중에게 공개하는 콘텐츠로 전환하기가 더 쉬워집니다.

클레이:
맞아요. Randall과 저는 외부 문서와 마찬가지로 내부 문서도 작업합니다. 많은 기술 문서 작성 그룹이 내부 문서와 외부 문서 중 하나를 선택해서 작업합니다. 하지만 저희는 두 가지 모두에 전념하며 그렇게 확장해 나가고 있습니다. 우리는 사람들이 자신과 커리어, 가장 중요한 사용자, 그리고 제품 자체를 위해 올바른 작업을 최대한 쉽게 수행할 수 있도록 지원합니다. 이를 위해 프로세스, 템플릿, 지침을 제공할 뿐만 아니라 직접 자료를 작성하는 데 직접적인 도움을 제공합니다. 필요한 모든 것을 제공합니다.

. . .

질문 #5: 좋은 문서의 기준은 무엇인가요?

Randall:
이것은 기술 작가로서 우리가 항상 스스로에게 던지는 마법의 질문과도 같습니다. 처음 테크 라이터로 시작했을 때는 모든 콘텐츠에서 80%의 긍정적인 평가를 받아야 한다고 생각했지만, 콘텐츠를 소비하는 다양한 유형의 사람들을 모두 고려해야 하기 때문에 실제로는 달성하기 어려운 목표입니다.

저에게 품질이 의미하는 근본적인 부분은 이 제품을 사용하는 사람이 이 설명서를 가지고 원하는 작업을 수행할 수 있는가 하는 것입니다. 그렇다면 품질 기준을 충족하는 것이라고 생각하지만, 그다음에는 다음과 같이 다듬어야 할 부분이 많이 있습니다:

• 주제를 쉽게 찾을 수 있나요?
• 필요할 때 필요한 정보를 찾을 수 있나요?
• 왜 이 일을 하고 싶은가요?
• 이제 이 작업을 마쳤으니 다음으로 무엇을 해야 하나요?

따라서 기본적으로 탐색 효율성이 향상됩니다. 이러한 기능 중 일부만 있어도 좋은 문서를 만들 수 있지만, 훌륭한 문서는 이러한 기능을 모두 갖추고 다른 많은 기능을 다듬어야 합니다.

클레이:
훌륭한 답변입니다. 구체적으로 말씀드리자면, 저에게 좋은 문서란 공백이 좀 있는 문서입니다. 저는 다윈 정보 타이핑 아키텍처의 열렬한 팬입니다: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

기술 정보는 세 가지 유형으로 분류할 수 있다고 명시되어 있습니다:

1. 개념: 이제 막 시작하는 경우, 학습 섹션의 개요 및 소개를 통해 Sui 에 대해 학습하는 데 시간을 할애할 것입니다. sui.io.
2. 작업: 절차, 방법 및 플레이북입니다. 빌드 섹션에서 찾을 수 있습니다. 여기에서 패키지를 설치하고, 스마트 컨트랙트를 만든 다음, 빌드, 테스트 및 게시할 수 있습니다.
3. 참조: 직접 모험을 선택할 수 있는 표, 데이터베이스, 개체 목록입니다. 탐색 및 기여 섹션에서 찾아보세요.

구조는 사용자가 단순히 관련 명령어나 샘플을 찾고자 할 때 개념적인 자료를 헤매지 않도록 하는 핵심 요소입니다. 저희는 사용자가 무엇을 해야 하는지 예측하는 중요한 사용자 여정 또는 CUJ를 기반으로 이러한 정보를 구성합니다. 도구가 아닌 사용자에 초점을 맞춥니다.

그리고 결과를 모니터링합니다: 애널리틱스, Discord, 내부 의견 등을 모니터링합니다. 얼마 지나지 않아 우리가 가진 것이 효과가 있다는 것을 알 수 있습니다. 그런 다음 해결해야 할 다음 문제, 즉 웹 통계에 나타나지 않는 격차를 찾습니다.

Jen:
또한 청중 중 일부는 좀 더 명확하게 알고 싶어 할 것 같은데, 중요한 사용자 여정이란 무엇을 의미하나요?

클레이:
기본적으로 중요한 작업에 대한 사용자 여정 맵입니다. 사용자 여정을 완료하기 위해 하루 종일 도구 기반 문서를 뒤적거리지 않고도 목표를 달성할 수 있도록 도와줍니다. 이 문서는 완료해야 하는 작업에 따라 사용해야 합니다. 하나의 목표를 달성하기 위해 몇 가지 도구를 사용할 수도 있습니다. 이러한 여정은 매끄러워야 하며, 꼭 필요한 경우가 아니라면 각 도구의 세부 사항으로 내려가서는 안 됩니다.

. . .

질문 #6: 테크니컬 라이터는 문서 작성 외에 어떤 일을 하나요?

Randall:
말씀드렸듯이 저는 네트워킹 관리자 출신이기 때문에 문서 작업 외에도 네트워킹 분야에서 더 많은 일을 할 수 있었습니다. 보안 테스트도 많이 했죠. UI 디자인도 했는데, 제가 원하는 대로 화면에 모든 텍스트와 문서 링크를 넣을 수 있어서 정말 좋았습니다. 우리가 생성하는 결과물은 사이트에 표시되는 콘텐츠이지만, 주된 역할은 디자인 토론이나 엔지니어링 회의에서 사용자 옹호자 역할을 하는 것입니다.

. . .

질문 #7: 잠재 고객을 어떻게 식별하나요?

클레이:
예를 들어, 저희는 앱 게임 개발자에게 집중했습니다. sui.io 그리고 의사 결정을 내리는 임원급 직원과 기술 리더를 대상으로 했습니다. 따라서 전자는 빌드 탭에서, 후자는 Learn 탭에서 제공되는 것을 볼 수 있습니다. 하지만 모든 사람이 개념을 알아야 하므로 Learn 문서를 먼저 제공합니다.

동시에 우리는 이제 풀 노드 러너와 곧 검증자를 보유하게 되었습니다. 저희는 오디언스가 계속 늘어날 것이며, 이들에게 좋은 정보를 제공하기 위해 모든 동료들과 협력해야 한다는 것을 잘 알고 있습니다. 이러한 세션은 격차를 파악하고 동료들과 협력하여 각 대상을 정의하고 회사와 에코시스템의 모든 사람이 이에 참여할 수 있도록 노력하는 데 큰 도움이 됩니다.

. . .

질문 #8: 커뮤니티로서 트위터가 도울 수 있는 가장 좋은 방법은 무엇인가요? 그리고 인정받을 수 있을까요?

클레이:
네, 좋은 질문입니다. 저희는 여러분 모두가 Sui 관련 작업을 강조할 수 있는 페이지를 기여 섹션에 만드는 것을 고려하고 있습니다. 예를 들어, 많은 분들이 콘텐츠 제작자라는 것을 알고 있는데, 여러분의 창의성을 강조할 수 있는 공간을 만들고 싶습니다. 물론 그렇게 하려면 내부적으로 여러 사람들과 협력해야 할 것입니다.

저희는 여러분 모두를 인정하고 싶기 때문에 모든 페이지 하단에 기여자를 나열하는 자동화된 GitHub 프로필을 인스턴스화했습니다. 여기에는 주로 기술 작가로서 기존 텍스트를 수정하고 새로운 섹션을 구성하는 데 도움을 주시는 여러분의 도움이 필요합니다. 당연히 이것이 우리의 역할이며, 우리가 해야 할 일입니다.

하지만 두 번째로 여러분이 하고 있는 모든 멋진 일들을 강조하고 싶습니다. Discord #콘텐츠 채널에서 많은 것을 보고 있습니다. 여러분 모두에게 커뮤니티 기여 페이지가 있는 파이프라인을 제공하면 말 그대로 여러분이 들어가서 여러분의 글과 연결된 표에 여러분의 창작물에 대한 한 문장 설명과 함께 사람들이 우리 사이트를 떠날 수 있도록 하고 더 많은 시선을 끌 수 있을 것입니다.

. . .

질문 #9: 기술 문서 작성에서 가장 보람을 느끼는 부분은 무엇인가요?

Randall:
저는 네트워크 관리자였고 매니지드 케어 회사에서 근무했습니다. 보험 청구를 승인하거나 거부하는 의사가 한 명 있었어요. 모든 사람들이 그에 대해 긍정적으로 평가하지 않는 경우도 있습니다. 그는 '야, 이거 멋지다, 가서 해봐'라고 말하는 사람이었습니다. 물론 일을 계속하고 싶으니 가서 일을 해내려고 노력하겠죠. 저는 몇 시간이고 몇 시간이고 그가 원하는 일을 하는 방법을 배우느라 시간을 보냈지만 그는 종종 그것을 사용하지도 않았어요.

업무를 수행하는 데 있어 가장 큰 장애물은 새로운 기술의 사용법을 배우고, 작동 방식을 익히고, 무엇을 더 해야 하는지, 그리고 모든 전제 조건 등을 파악하는 것이었습니다. 이제 기술 작가로서 제가 하는 모든 일은 사람들이 업무를 더 잘할 수 있도록 돕는 일이며, 이것이 제가 매일 출근하는 이유입니다. 제 일을 잘하면 수십억 명의 삶에 영향을 미칠 수 있습니다.

젠:
굉장해요. Mysten의 세계와 Sui 에서 우리가 추진하고 있는 몇 가지 사항을 가장 쉽게 이해할 수 있는 방법을 제공하고자 하는 클레이와 랜달이 얼마나 도움이 되고 공감하는지 아무리 강조해도 지나치지 않습니다.