본문 바로가기

테크니컬 라이팅/WTD 컨퍼런스

WTD 포틀랜드 2022 - 테크니컬 라이터와 개발자의 협업에 대해

반응형

개인적인 정리

원래 이름은 Ian Dees였습니다. Ian Dees라는 이름으로 테스팅 관련 분야에서 꽤 많은 책을 쓴 것을 찾아볼 수 있습니다.
https://www.amazon.com/Ian-Dees/e/B002BM9GLE

개인 스타일링 서비스를 제공하는 스티치 픽스(STITCH FIX)라는 곳에서 2019년부터 소프트웨어 엔지니어로 일하고 있습니다(라고 이력서에는 나와있는데 발표를 보니 briza.com에서 일한다고 합니다). Cowpoke는 카우보이를 뜻하는 미국식 구어라고 합니다. Wrangler도 카우보이인데 주로 목장 내에서 말을 돌보는 일을 하는 이들을 뜻한다고 합니다. Cowpoke는 외근직, Wrangler는 내근직이라고 할 수도 있겠네요.

개발자와의 협력을 강조하며 여러 가지 장점을 설명하는데 그중에서 예외적인 상황(corner case)에 대해 사용자에게 설명하기 위해서는 개발자와의 긴밀한 협조가 필요하다는 겁니다.

API 문서 개발에 대한 실제 사례를 소개해줍니다.
내부적으로 용어에 대한 표현이 변경(Binder > smart portal)되었는데 테크니컬 라이터가 문서를 검토하면서 예전에 사용하던 용어가 포함된 필드명(hasBinderAccess)을 발견했습니다. 문서화 과정에서 더 좋은 아이디어를 발견할 수 있고 좀 더 좋은 사용성을 가진 API 구현을 할 수 있다는 이야기입니다.

 

 

이런 경험을 통해 필드명을 안전하게 변경하는 가이드를 만들었습니다(이건 직접 만든 건지 아니면 일반적인 규칙인지 좀 애매하긴 합니다).
1. 누가 엔드포인트를 사용하는지 확인하고(Find out who's using the endpoint)
2. 이를 변경한다는 것을 알려주세요(Let them know you're making a change (ask a tech writer for help!))
3. 이전 필드와 새로운 필드를 모두 처리할 수 있게 하고(Accept both the old and new fields)
4. 여전히 이전 필드를 사용하는 이들을 적발합니다(Instrumen who's still using the old field)
5. 모든 사용자가 새로운 필드를 사용하게 되면 이전 필드를 정리합니다(Only clean up after everyone's using the new field)

개발자와 테크니컬 라이터가 다른 도구로 사용하는 것은 상당히 불편한 일입니다.
업무 외적인 만남(점심식사 등)을 통해 공동 작업에 대한 아이디어를 찾아보세요.
좋은 아이디어에 대해서는 금전적인 보상을 하는 것도 좋습니다.

그 외에 프로세스에 문서화를 포함시키라는 이야기는 딱히 새롭지는 않습니다.
풀리퀘스트 요청 시 문서에 대한 건은 템플릿으로 만든 체크리스트를 미리 체크하도록 하거나 하는 등의 아이디어가 있다고 합니다.

 



Q&A

내부적으로 테크니컬 라이터가 어느 정도까지 참여할 수 있나요?

테크니컬 라이터가 설명하기 어렵다면 기술 자체가 어려울 수 있습니다. 테크니컬 라이터는 사용자 입장에서 기술을 바라보기 때문이죠. 때문에 테크니컬 라이터가 일찍 참여하면 그만큼 제품을 개선할 여지를 가질 수 있습니다.

 

영상

https://youtu.be/I9g8b4iWD1I

현장 스케치

https://flic.kr/p/2nnDGZH

 

Erin Dees - Code Cowpokes and Word Wranglers: from Mutual Admiration to Solidarity

Explore writethedocs' photos on Flickr. writethedocs has uploaded 2645 photos to Flickr.

www.flickr.com

 

728x90