개발자의 글쓰기 행사 참여 후기 + Docs for developers 를 읽은 후기

예전에 Docs for Developers를 구매해두고 많이 읽지 못해서 아쉬웠는데 이번 행사를 보고 읽고 참여해봐야겠다 싶어서 진행해보았다.

행사 소개

• 행사명 : 개발자의 글쓰기
• 부제 : 업무적인 글쓰기로 커리어 up 하자.
• 장소 : 튜링의 사과
• 강연자 : 남정현님

강연 내용 정리

• 기업이 성장함에 따라서 지식 부채가 발생된다.

• 문서화는 중요하다. 문서화는 왕이다.

• 문서 : 너무 없어도 너무 길어도 매력적이지 않다. (e.g. README.MD)

  • 엘리베이터 피치(elevator pitch)
    • 엘리베이터 피치란 어떤 상품, 서비스 혹은 기업과 그 가치에 대한 빠르고 간단한 요약 설명

• 핵심 문장 성분만 남기기

  • 단순하고 명확하게

• 쉬운 우리말과는 친해지고, 번역체는 멀리하기

• 다른사람의 글을 읽어보고 나라면 이렇게 할 텐데 생각도 해보기

• 일관된 글쓰기

  • 보그체, 애플 스타일 …
  • 큰 기업들은 writing style guide 문서 있음.
    • Apple Style Guide:
      • https://support.apple.com/kokr/guide/applestyleguide/welcome/web
    • Microsoft Writing Style Guide:
      • https://learn.microsoft.com/enus/styleguide/welcome/

• 업계에서 굳어진 용어 vs 국립국어원 (솔루션 vs 설루션, 리팩토링 vs 리팩터링) 굳어진 용어를 사용해도 문제가 되지 않음 (국립국어원 피셜)

• 용어집부터 만들어보기

그 외에 책에서 기억에 남은 것

이 책은 짧지만 매우 전문적이였다. 그렇기 때문에 그래서 일반적인 개발자가 읽었을 때는 업무랑 조금 벗어난 느낌이지 않을까 싶었다. (테크니컬 라이터가 무슨일을 하고, 문서를 이런 과정으로 써가고, 어떤 것들에 포커스를 맞추고 있는지 대략적으로 알 수 있는 기회 정도의 느낌으로 읽어나갔다.)

중요한 것을 문서 위쪽에 배치하기

이거는 한 번 조언을 받은 적이 있다. 잘 지켜줘야겠다.

좋은 피드백 제공하기 (픽사 사례)

픽사에서는 피드백을 제공할 때 플러싱(plussing)이라는 규칙을 따라야 합니다.

건설적인 제안을 덧붙이는 경우에만 아이디어를 비판할 수 있습니다.

피드백을 제공할 때는 사람이 아니라 아이디어에 집중하세요. 예를 들어 “이 부분을 잘못 하셨네요.”가 아니라 “이 부분이 명확하지 않아 보입니다.”와 같은 말로 시작해 봅니다.

비판을 제기한 다음에는 개선을 위한 구체적인 제안을 제공하세요. 건설적인 제안은 문제의 해결책이 될 거라 생각하는 방안에 대한 맥락을 추가로 제공합니다.

이 더하는 행위가 픽사가 이 시스템을 플러싱이라고 부른 이유입니다.

건설적인 제안이 더 구체적일수록 피드백이 더 좋아지고 사용자에게 더 많이 도움이 될 수 있습니다.

건설적인 피드백을 많이 덧붙인다면 문서 작성자에게 제안을 고려할 시간을 주세요. 사람들은 피드백을 받고 평가하고 구현하는 데 시간이 필요합니다. 특히 검토자가 여러 명이라면 즉각적인 응답을 기대하지는 마세요.

정리하면 다음과 같습니다.

• 사람이 아니라 아이디어에 집중하기
• 건설적인 제안 덧붙이기
• 피드백을 받는 사람이 피드백에 반응할 시간 주기

좋았다고 생각한 부분에도 피드백을 남기세요

질문드렸던 것

“글을 작성하고 나면 언젠가는 옛날 것이 된다. 옛날 것이 되면 관리가 쉽지 않다. 레거시가 된다. 이러한 상황을 어떻게 개선할 수 있을까?” 에 대한 질문을 드렸었는데

짧게 말하면 프로세스 안에 포함시켜야 한다고 이야기 해주셨다.

사실 테스트의 경우에도 지속적인 관리를 위해 팀원들의 동의와 도움이 필요하다. 문서화도 마찬가지 인 것 같다. 팀 모두의 동의와 참여가 있는 상태가 아니라면 하기 쉽지 않은 것 같다.

기타

• 튜링의 사과에 처음 알게 되었고 처음 가게 되었는데 주변분들중에 아시는 분들도 있었고, 해당 장소를 자주 사용하시는 분도 있으셨다. 개발자들을 위한 서점이라니 재미있었다.

• 관련 글

  • Line의 전정은 님의 글 - 문서 엔지니어링과 API 문서화

  • 카카오엔터프라이즈 테크니컬라이팅 팀의 [TW] 기술문서 쉽게 쓰기 지침