Blog

#이상한 글쓰기의 이상한후기

May 31, 2015

#이상한 글쓰기의 이상한후기

blogging

이상한 모임 5월 세미나 #이상한 글쓰기에 참가를 하였고, 평소에 글쓰기에 대해서 그리고 기술블로그를 운영해오는 입장에서 다른 사람들은 어떻게 운영하고 있는지에 대해서 궁금해서 유료임에도 불구하고 참가하게 되었다. 순서는 다음과 같았고, 간단하게 들은 내용을 요약해 보도록 하겠다. 

12:00 ~ 12:45 참가등록  12:45 ~ 13:00 키노트

Session1. 테크니컬라이팅 

13:00 ~ 13:30 테크니컬라이터 구인공고 / 김진중, 골빈해커 (옐로트래블) 13:30 ~ 14:00 이상하지 않은 API 글쓰기 / 김주아(다음카카오)

Session2. IT출판

14:00 ~ 14:30 출판 기획편집자가 바라보는 IT개발자의 글쓰기 / 이중민(한빛미디어)

14:30 ~ 15:00 컨텐츠의 힘을 싣는 글쓰기 / 현지환(제이펍출판사)

Break Time(30′)

Session3. 기술블로그

15:30 ~ 16:00 스포카 기술블로그의 원칙 / 김재석(스포카)

16:00 ~ 16:30 변정훈(SK Planet)

Session4. IT미디어

16:30 ~ 17:00 KudoReview 제작과정 / 이주형(Kudo Networks)

17:00 ~ 17:30 배우지 않은 개발에 대해 말하는 법 / 남혜현(마이크로소프트웨어)

키노트, 김민경

계속 글을 써야 한다. 개발자라서 못 쓰는것이 아니라. 잘 쓰는데 안쓰는것. 

사람에 대한, 자신의 이야기를 먼저 쓰는것에서 시작해라. 스타트업일수록  사람에 대한 이야기를 쓸것. 

경험에 대한 이야기 – 누구나 볼 수 있다. 경험에서 시작해라. 

기술에 대한 이야기 – 자기 자신을 위해서라도 블로그를 해라, 메모장에 써 두지 말고. 

테크니컬라이터 구인공고 / 김진중, 골빈해커 (옐로트래블)

직업이 세분화 하면서 테크니컬 라이터가 급부상 하고 있다.  단순한 일이 아니다. 문서를 작성하는 것보다  어떤 문서를 작성하는지, 왜 문서를 만들어야 하는지  문서를 만드는 프로세스가 더 중요하다. 

사용자 문서  스펙 문서 : 기능 구현 API 라이브러리 사용자를 위한 문서 

마이크로 소프트, 애플에서 잘 하고 있지만,  작은 회사도 잘해야 한다. 왜? 이것이 중요한 회사가 되었다.  혼자 개발하는 회사가 없다. 다 가져다 사용하기 때문에 API의 사용이 중요하다.  API 구현 보다 중요한것이 사용하게 하는것. 문서를 잘 만들어야 한다. 

API is Everything. 

유명한 라이브러리는 문서화가 잘 되어 있다. js 라이브러리의 경우 굉장히 문서화가 잘 되어 있다.  개발하는것보다 다른사람이 쓰게 하는것이 더 중요한 시대이다. 

문서화가 중요한데, 어떻게 쉽게 찾게 할것인가? 가 중요하다.  어떻게 쉽게 쓰게 할것인가?

기술을 잘 모르는 사람에게 어떻게 설명한것인가? 도메인이 서로 다른 사람들에게 어떻게 설명 할 것인가? => 인터뷰 하면서 샘플 프로젝트를 만들면서 튜토리얼 형식으로 설명 

예제, 혹은 각 언어별 SDK 를 개발/배포  십수개의 API 를 쉽게 잘 쓸수 있다. 

단순히 글을 쓰는것 보다, 어떻게 무엇을 전달해서 쉽게 접할수 있게 할것인가가 중요.  테스트는 postman을 활용. 

더미 데이터를 이용해서 스펙공유  프론트 엔드나, 백엔드에서 준비가 되기전에

구인을 하는 이유 – 설명이 필요한데, 잘 못쓰겠다.  – 구현자와 사용자 입장을 동시에 대변해야한다.  – 좀더 보기 좋았으면 좋겠다.

대부분 구현하는 입장에서 서술, 그래서 실패하는데 쓰는 입장에서 다시 봐야 한다. 

이상하지 않은 API 글쓰기 / 김주아(다음카카오)

열심히 써도 문제가 생기기 까지 잘 보지 않는것이 API문서이다.  

4가지 요소만 잘 갖추면 된다. 

OVERVIEW – 전반적인 소개 , 함축적인 내용을 담고 있는 경우가 많다.  – 문서 사이트의 가장 첫 페이지  – Introduction…

GETTING STARTED – 시작하기, 차례차례 따라할수 있는 형태로 구성

SAMPLE CODE – 정말 중요하다. 코드를 실행시키는 법  – 개발자들이 바로 사용할 수 있는 코드  – 실제로 동작해야함. 

REFERENCE MATERIAL – 클래스 멤버 등의 가장 자세한 정보를 명시  – 응답값 등등 API에 대한 설명. 

도구  – 마크다운, 위지윅 활용, GITHUB 위키, 에버노트 등등 – QUIVER, SWAGGER 

내부적으로 공감하는 마음에서 API문서를 써라.  보기좋은 떡이 먹기도 좋다.  각종 프로그래밍 언어로 샘플코드로 제공하는 것이 좋다.  Getting Started 도 중요하다. 테스트 할수 있다면 더 좋다. 

출판 기획편집자가 바라보는 IT개발자의 글쓰기 / 이중민(한빛미디어)

개발자가 문학적인 글 쓸필요는 없다. 로지컬한 글을 쓰는 경우가 더 많다.  개발자는 귀찮아서 안쓴다. 자신감의 결여가 문제 

설명 + 예제코드 , 자세한것을 링크를 참고하라고 안내 

“자신감을 좀 가져주세요”

글쓰기의 본질 맞춤법과 오탈자는 치명적이지 않다.  개발자의 효율성도 중요하지만, 글을 여러 사람이 본다. 다른 사람이 모를수 있다.  알아야 할 부분은 정확히 안내해주고, 말하고 싶은것을 잘 쓸것. 

문법 검사기, 맞춤법, 오탈자 교정기를 사용함. (fallroot.github.io/dandy)

완벽하게 글을 쓰는 사람은 없다.  핵심을 잘 설명할수 있으면 OK 편집자는 보완할수 있는 존재. 

책을 내고 싶다, 번역을 하고 싶다 – 자신있게 지원해달라. 

컨텐츠의 힘을 싣는 글쓰기 / 현지환(제이펍출판사)

출판과정

기획 – 설계(목차) – 구현(본문) – 테스트(탈고) – 출시

기획 단계  – 소재와 독자 대상  – 소재 : 유행이 존재, 유행을 선도하는 내용 또는 꾸준하면 OK – 독자대상 : 입문서가 따봉 > 실용적인 도서 굳 > 고급은.

설계단계(목차) – 흐름을 갖거나, 모듈화하거나(와치킷, 헬스킷 등등) – 균형감이 중요 : 읽는 사람을 고려, 스터디 하는 사람도 고려애서 양을 조절  – 목차가 중요하다. 어렵다. 

목차를 잡는 단계 : 다른 유사도서의 목차 참고하고, 구성방식 결정, 챕터구성, 소챕터 구성, 수정수정수정 

구현(본문)

  • 우리말 공부 
  • 비문제거 할것 : 문법에 맞지 않는 문장(네이버 국어사전)
  • 주술불일치, 목적어-술어 불일치 : 문장이 길면 발생, 단문으로 끊어가라.

  • 조사의 오용 : 외래어의 경우 주의 

  • 접속사의 오용 

  • 맞춤법은 툴에 의존

  • 지양해야함 : (사실, 솔직히 말해서, 개인적으로 나름대로, 아마도 아무튼) 객관적이지 못하고, 신뢰성을 떨어뜨린다. 

  • 예를들어 설명하기(컨텐츠의 힘을 실는다.)

  • 표, 그림, 코드

테스트(탈고) – 원고에 대한 리팩토링, 꼼꼼함이 중요  – 원래의 기획의도와 부합하는지에 대한 점검 

정리  – 기획과 구성을 잘 만들자  – 우리말 공부를 열심히 하자.   

스포카 기술블로그의 원칙 / 김재석(스포카)

기술블로그 쓰게된 계기  매일매일 새로운 오픈소스가 나온다. 특정 기술에 대해서 공부하고 공유 해야하는 일이 생김.

컨텐트의 원칙 – 어디에도 찾을수 없는 정보? => 한국어 기준 => 어렵다.  – 다른데 있으면 굳이 할 필요가 있는가

주로 쓰게되는 글  – 주요 외국 문서  – 일하면서 읽는글들의 번역 및 요약 – 추천컨텐츠 모음  – 여러 문서 링크의 조합 – 내부 기술 방법론 공유  – 기존의 방법론에서 개선된 사항.  – 회사에 대한 소개  – 기술 사용에 대한 케이스 스터디  – 써봤더니 어떻더라.  – 통찰보다는 경험위주. 

바쁘다는 것 – 안 바쁜데는 없다.  – 글을 쓰는것을 새로운 일을 한다고 생각하지 말자. 

글쓰기가 개발자의 기본 교양으로 여겨 졌으면 한다. 

기술블로그로 얻는 효과 – 팀역량 강화 – 무언의 압박이 있고, 좀더 대충하지 못하게된다. – 효과적인 메뉴얼 – 새로 입사하는 분들에게 좋음, 입사전에도 읽고 볼수 있음. 

채용도 락밴드 처럼 – 성향이 맞는 사람들끼리 만나는 역할이 있어야 함. – 사용하는 기술을 애기하고, 좀더 섬세하게 이야기 할수 있음.  – 기술블로그를 통해서 채용과정에서 취향의 차이를 줄일수 있다. 

블로그 주도 개발 변정훈(SK Planet)

왜 기술 블로그를 운영하는가  까먹는다.  처음에는 스프링노트 => 모르겠음 찾는건 결국 구글  퍼가기식 => 습득이 없다. 

공개적으로 쓴다는것은 다름 사람(한달이나 1년후의 나)이 이해할수 있게 써야 한다. 

기본원칙 : 알게된 내용은 모두다 적는다. 모르는 누군가는 있기에.  설치과정 등 자주 반복하지 않는 내용 문제 상황에 대한 파악 => 블로그를 쓰면서 문제상황 파악에 관련된 훈련을 하게 됨.  블로그를쓰면서 평소 안보던 내용에 대한 공부 (예. jshint 에 대한 옵션정리) 공개적으로 적으려면 그 만큼의 이해가 필요  번역글 : 영어를 잘 못해서 번역, 원저작자에게 허락을 받는다. 

시간을 들이지만 얻는것도많다. 

블로깅와 오픈소스가 닮아 있다. 재밌으니까 하는것.  정리하고 적는 행위가 상단한 큰 효과가 있다. 

블로그와 개발의 선 순환(글감과 개발의 선순환)

기술블로그는  롱테일에 가깝다. 퍼지는 것은 제한적. 관심있는 사람들이 본다.

기술적인글 보다 일반적인글(개인적인 경험)이 좀더 많이 퍼진다.  블로그는 마크다운으로 쓰고. 데이원을 쓰고 서브라임 텍스트를 쓰고. 

KudoReview 제작과정 / 이주형(Kudo Networks)

예술작품에 대한 리뷰가 원래의  Review

도구를 가리지 않는다.  생각 나는것을 트위터에 올리는 것으로 기억하고 활용  몰아서 찍지 않는다. 자연스러운 사진을 찍으려고 한다. 

배우지 않은 개발에 대해 말하는 법 / 남혜현(마이크로소프트웨어)

IT에 대해서궁금해 하는 사람이 많고 비전공자가 쓰면 쉽다. 

내가 이걸 왜 쓰는가?를 생각해보자. 목적을 생까해 보자.

체력훈련 – IT 관련 기사 뉴스, 관련련도서, 칼럼을 정독해라. – 아침에 주요외신 챙겨보기

실전 투입 – 주재를 정하지 않았다면 검색을 외신을 통해서 – 외신 번역은 라이센스 중요

사람 돈 애기를 좋아한다. 어떻게 돈을 벌었는가 등등 결국 사람이 하는 일 

쓰는 추천 법

  • 사람에게 직접 만나기, 이메일은 비추, 최소한 전화라도 할것.
  • 쓰기전이 5분 깊이 생각해봐라
  • 써야하는 주제가 있다면, 머리속에 개요를 짜라 70프로 정도
  • 시간을 정해놓고 써라
  • 멈추자 멀고 계속 써라
  • 완벽핱 공정은 없다. 본인 입장을 정리해서 써라
  • 무조건 쉽게써라
  • 맞춤법 중요 
  • 자신감을 잃지마세요.
  • 간결하게, 스케치하게 써라

퇴고

  • 바로 보지 마라
  • 다시 읽기 천천히
  • 동료에게 보여줘라
  • 댓글은 골라서 읽어라
  • 상처받지마라

개인적인 의견

글쓰기라는 주제에 대해서 이렇게 진지하게, 그리고 다양한 측면에서 이야기해 본적이 있었던가. 나의 글쓰기에 대해서 글을 쓰는 이유에 대해서 나중에 다시 쓰겠지만, 이번 세미나에 대해서만 말하자면 좋았다는 말로 다 하긴 어려울것 같고, 이상한 모임의 지난 연말정산때 부터 쭉 참여를 하고 있는데(다는 아니고), 점점 발전 한다는 생각이 들었다. 특히 쉬는 시간에 서로 만나서 이야기 하는 모습(나는 왜 이게 안될까..?)과 나와서 스타트업을 소개하는 모습등등. 점점 더 어떤 모습으로 다음에는 발전할지 궁금해 지는 모임이다. 

와이프가 보틀을 가져왔더니 좋아한다.  얼른 티셔츠 받고 시프다.  슬랙스티거 떙큐!!

The post #이상한 글쓰기의 이상한후기 appeared first on LAB84.