How to Write Helpful Code Samples 라는 글입니다. Sarah Maddox는 구글에서 테크니컬 라이터로 일하고 있으며 그 전에는 아틀라시안, HP 등에서 일했다고 합니다. 9년 동안은 엔지니어로 그 후로는 테크니컬 라이터로 일하고 있네요.
현재 하고 있는 일이 주로 구글맵 관련된 일이라서 그런지 주로 구글맵 사례로 설명을 해주고 있습니다. 블로그에 올린 글 중에 How to write sample code 라는 글이 있는데 내용은 비슷한 것 같네요.
http://ffeathers.wordpress.com/2013/12/21/how-to-write-sample-code/
이전 글에서 다룬 것처럼 API 문서에 들어가는 텍스트 영역은 사용자가 직접 접하는 부분이고 누구나 쉽게 사용할 수 있게 풀어주어야 하기 때문에 별도 라이팅 역할이 필요하다고 하지만 샘플 코드는 좀 애매한 영역이 아닌가 싶습니다.
하지만 독자층을 생각하면 샘플 코드 자체도 하나의 콘텐츠고 관리가 필요한 영역이라는 주장입니다.
...To a developer, a code sample speaks a thousand words. Skimming code samples in a document is like skimming headings for the rest of us. As technical writers, we are trained to create clear and meaningful content. And code is content...
실제 저자는 글쓰기나 샘플 코드 만들기 같은 작업만 하는 것이 아니라 기술 자체에 대해 직접 설명하기도 합니다.
샘플 코드는 명확한 목적을 가지고 그 목적에 맞게 만들어져야 합니다. 샘플 코드를 직접 작업중인 코드에 추가할 것인지, 아니면 개념적인 이해를 위한 것인지 분명하게 구분이 되어야 한다는 것이죠.
또한 이런 구분을 사용자가 쉽게 인지할 수 있어야 합니다.
상황에 따라서는 개발자가 만들어진 문서보다는 코드만 보고 있을 수도 있습니다. 실제 많은 경우 그럴 수 있죠. 이때는 코드 내 주석도 중요한 역할을 합니다. 그렇기 때문에 코드 주석도 하나의 콘텐츠로 중요하게 다뤄져야 한다는 거죠.
...And our target audience, also developers, will often read code comments where they don’t read other documentation. So code comments are a great medium for technical communication!...
