API Writer가 되려면

 

이 글은 테크니컬 라이팅과 픽션에에 대한 블로그를 운영하는 Sarah Maddox의 홈페이지에서 본 To become an API writer 포스팅을 번역하고 그 글을 읽고 든 생각을 정리한 글입니다.

 

---

 

글쓰기
글쓰기에 관해서는 사용자 중심 기술 글쓰기와 다르지 않다. 사용자 매뉴얼처럼 사람들(개발자)에게 어떻게 그것을 사용해야 하는지 말하는 것 뿐이다. 이 경우, 다루는 것은 API, SDK 또는 다른 툴이 될 수 있다.
예전에 존경 받는 개발자들에게 그들이 가장 좋아하는 기술문서 사이트에 대해 물어보았다. 결론은 이 포스팅에 있다: What developers want. 이 포스팅과 코멘트란에 유용한 링크가 있다.
build a developer documentation wiki
또 다른 포스트는 개발자 문서를 구축하는 프로젝트로 유용한 링크와 팁을 담고 있다.

기술
기술 면에서 HTML, CSS, JavaScript와 같은 웹 기술의 기초를 알아야 한다. W3Schools에서는 이런 기초를 시작하는데 필요한, 그리고 정체된 지식을 새롭게 할만한 좋은 수업을 무료로 제공한다.
특정 회사에서 일하는 것이 목표라면 그 회사의 개발자들이 어떤 기술을 사용하는지 파악하고 그 기술들을 습득해라. 또한 널리 사용되는 프로그래밍 언어를 고르는 것도 좋다. 다른 회사는 API 테크니컬 라이터에 대한 요구사항이 다르다. 어떤 회사에서는 기준이 꽤 높다. 코드 샘플을 직접 써야하고 다른 개발자가 쓴 코드를 리뷰도 해야한다. 또 어떤 회사에서는 코드를 읽기만 해도 충분하다.

태도
개발자들을 위한 테크니컬 라이터는 API와 SDK를 사랑해야 한다. 그것들을 관심있게 보는한, 그것은 세상의 미래이다. 개념에 몰드하고 전문 용어(Buzz words)를 습득해라. 기술을 가지고 놀아라. 해커 뉴스(HM)는 개발자들의 인기 토론 사이트다. 정기적으로 들러 그 날의 가장 인기 있는 주제를 보아라. HN은 기술 주제, 모든 종류의 공학, 정치, 사회, 그리고 그 밖의 다른 것들을 가지고 있다. 처음에는 기술 주제들이 낯설겠지만, 몇 주 후에는 기술들을 잘 습득하기 시작할 것이다.

API 실습
가지고 놀만한 위대한 API가 많다. 한 두개의 api를 이해하는 것은 api와 동반한 문서들에 대해 알려줄 것이다.예를 들어
이 글에서는 Google Maps JavaScript API와 같은API로 연습할 것을 추천한다.
Google Maps를 사용하면 그 API가 제공하는 특징들을 파악할 수 있다.
텍스트 에디터로 HTML페이지를 구축하면서 그 API를 사용해볼 수도 있고, 튜토리얼로부터 jAVAsCRIPT샘플을 복사 붙여넣기 할 수도 있다.

---

 

+ 이 기사에 달린 어느 댓글:

I think the best way to be a technical writer that writes developer documentation is to write some developer documentation. This is less obvious than it sounds. A good way to start would be to write a tutorial for some API, even if there’s already one or more tutorials available. It’s good practice for the writer, both as a matter of writing and of understanding the software. Another route is to make something and then document it. I did this recently with a ludicrously simple open source Python library that I wrote, but it was still warmly received and good practice writing docs and Python.
Another good way to learn the technologies is to go to meetups for stuff you’re interested in. When I lived in Washington, DC, I loved going to the DC Python Meetup. I was sometimes out of my depth, but I learned something new, interesting, and useful every time. (And I even got to give a presentation myself about creating documentation, so there was give as well as take)

---

 

나는 회사에서 사용자 중심의 기술문서를 주로 작성한다. 글쓴이의 말처럼 개발자를 위한 글쓰기는 사용자 중심 기술 글쓰기와 다르지 않다. 개발자를 위한 API, SDK문서들도 개발자들에게 어떻게 그것을 사용해야 하는지 말하는 것이기 때문이다. 하지만 나는 그러한 문서들에 대한 경험이 없으니, 글쓴이가 개발자들에게 추천 받은 What developers want, build a developer documentation wiki의 문서들을 통해 어떤 문서가 잘 만들어진 문서이고, 어떤 점에서 개발자들에게 직접적인 도움이 되는지 분석해보면서 나만의 경력을 쌓아야겠다.

API 분석에 관한 글은 일단 뒤로 미루고, 이제 내가 역량을 더 키우고 싶은 ‘기술’에 관하여 말해보자. 
글쓴이는 기술 면에서 HTML, CSS, JavaScript와 같은 웹 기술의 기초에 대한 중요성을 강조하였다. 나는 이를 위해 도서와 유튜브 강의, 특히 ‘생활코딩’님의 강의와 프로젝트를 통해 익혔다. HTML, CSS는 대부분 이해되었으나 JavaScript, JAVA 강의는 뒷부분으로 갈수록 어렵게 다가왔다. 
배운 걸 직접 써먹어야겠다는 생각에 나만의 웹사이트를 구축하겠다고 처음부터 코드를 짜봤는데, 직접 내가 원하는 디자인을 만드는 건 여간 까다로운게 아니었다. 내가 Web Developer가 될 것도 아니고, 디자인 하나 바꾸겠다고 너무 많은 시간들이 소요되어 다른 방법을 알아보기로 했다.
나의 웹페이지 만들기와 관련해서는 다른 포스팅에서 따로 다루기로 하고 , 글쓴이가 추천하는 것처럼 Google Maps JavaScript API를 교재 삼아, API를 가지고 놀아볼까 한다. 튜토리얼로부터 JavaScript 샘플을 복사 붙여넣기 하는 것부터 시작하여 API를 직접 이용해보면 사용방법 및 특징들도 파악할 수 있고, API 문서에서 실질적으로 내가 어떤 부분에서 도움을 받는지, 어떠한 설명이 더 있으면 좋겠는지 파악할 수 있겠지.
그러고 나서 더 다양한 종류의 API 문서를 보면서 구성과 형식들을 익히고, 이 글에 댓글을 남긴 누군가의 조언대로 직접 API문서를 만들어보면 좋을 것 같다. 개발자들을 위한 테크니컬 라이터는 API와 SDK를 사랑해야 한다고 말하는 글쓴이의 말에 LOVE까진아니어도 FAMILIAR까지는 해봐야지.

특정 회사에서 일하는 것이 목표라면 그 회사의 개발자들이 어떤 기술을 사용하는지 파악하고 그 기술들을 습득해라. 또한 널리 사용되는 프로그래밍 언어를 고르는 것도 좋다. 다른 회사는 API 테크니컬 라이터에 대한 요구사항이 다르다. 어떤 회사에서는 기준이 꽤 높다. 코드 샘플을 직접 써야하고 다른 개발자가 쓴 코드를 리뷰도 해야 하는 반면, 어떤 회사에서는 코드를 읽기만 해도 충분하다. 

내가 단 기간에 개발자처럼 코드를 쓰는 능력을 기르는 것은 사실상 어렵고 일차적인 목표는 코드를 읽고 이해하는 것에 두기로 한다. 위의 계획대로만 한다면 그 목표는 이룰 수 있을 것 같은데 시간이 조금 더 걸리더라도 꾸준히 앞으로 나가는 것이 중요할 것 같다. 꿈을 현실화 하려면.