2009년 2월 16일 월요일

개발자도 문서를 잘 작성할 수 있어야 한다.

개발자(엔지니어)들이 문서를 잘 작성하지 못한다는 것은 익히 알려져 있는 사실입니다.
 
개발자에게 프로그래밍 실력이 더 중요하지 문서 작성 기술이 얼마나 중요하겠냐?라고 생각하는 사람이 있을 수도 있겠지만, 개발자가 성장할수록 문서 작성 능력의 중요도는 점점 더 커집니다.
 
문서를 잘 작성하지 못하는 개발자는 협업을 하는데 있어서 치명적인 결함을 가지고 있다고 할 수 있습니다.
 
그럼 문서를 잘 작성하는 것은 무엇이고? 문서를 잘 작성하지 못하는 것은 무엇일까요?
잘 작성되지 못한 문서의 특징을 한번 살펴보죠.
 
  • 문서의 내용이 쉽게 이해가 되지 않는다. 외계어로 작성된 것 같다.
  • 여백 없이 빽빽이 작성되어서 읽는데 너무 피곤하다.
  • 문법이 많이 틀려서 내용도 신뢰가 가지 않는다. 주어도 없고 문장의 앞뒤가 전혀 맞지 않는다.
  • 주변 얘기만 빙빙돌려서 하고 있고 핵심이 뭔지 잘 모르겠다.
  • 내가 관심있는 내용은 없고 작성자의 관심거리만 적혀있다.
  • 사용하고 있는 단어들이 너무 전문적이고 어렵다.
  • 분량이 너무 많아서 읽기 힘들고 주제 파악이 힘들다.
 
물론 개발자라면 개발에 필요한 핵심문서를 잘 작성할 수 있어야 합니다. 하지만, 이같이 기본적인 문서작성 기술도 없다면, 개발문서라고 해서 잘 작성할 수는 없습니다.
 
"조엘온소프트웨어"의 저자인 조엘 스폴스키는 개발자를 뽑을 때 글을 잘 쓰는 사람을 뽑는다는 원칙이 있다고 합니다. 글 쓰기 능력을 키우는 것은 프로그래밍 실력을 키우는 것보다도 더 어려울 수 있습니다. 그래서 아예 글을 잘 쓰는 사람을 뽑는 것이 더 합리적으로 보이기도 합니다.
 
개발자들은 문서를 잘 작성하지 못한다는 얘기는 어디서나 통하는 말이지만, 특히 우리나라의 개발자들은 단순 주입식 교육 환경 때문에 읽고, 외우는 것은 잘하지만 자신의 의견을 남들에게 쉽고 조리있게 전달하는데는 익숙하지 못합니다. 그렇다고 문서작성을 포기할 수는 없죠. 평생 혼자서 개발할 것이 아니라면 문서는 점점 더 필요하게 되죠. 아니 혼자서 개발을 하더라도 문서를 잘 작성하는 것이 필요합니다.
 
그럼 문서 작성 실력을 키우기 위해서 어떻게 해야 할까요? 역시 훈련이 필요합니다. 단순히 여러 번 작성해 본다고 되는 것이 아니라 제대로 작성하기 위해서 노력해야 합니다. 이제, 문서 작성 실력을 향상하기 위한 몇 가이드를 하려고 합니다. 그 출발점은 다음과 같습니다.
 
"문서작성 기술이 필수 기술이라는 것을 먼저 인식해야 합니다."
 
필요성을 못 느끼면 발전도 없습니다. 그리고 문서를 잘 작성하려면 다음과 같은 것을 고려해야 합니다.
 
  • 문서를 작성하는 목적은 내가 일기 위한 것이 아니고 남이 읽기 위한 것이다. 읽는 사람의 눈높이에 맞춰서 적절한 단어를 사용해야 한다.
  • 주제를 직설적으로 전달해야 한다. 문서를 읽는 사람은 친절하게 문서를 처음부터 끝까지 다 읽어 줄만큼 한가하지 않다. 주제를 먼저 전달함으로써 문서를 읽는 사람이 문서를 계속 읽을지 말지 결정할 수 있도록 해야 한다.
  • 필요한 내용을 쓴다. 문서 작성의 목적을 달성할 수 있도록 문서를 읽는 사람이 기대하는 내용을 충분히 적어야 하며 자신만 관심 있어 하는 필요 없는 내용은 쓰지 않는다. 이런 내용들은 문서의 양만 늘리고 문서의 가치를 떨어뜨린다.
  • 사실과 의견을 확실히 구분하여 작성한다. 사실과 의견의 혼동은 수많은 오해를 불러일으키게 된다. 심지어는 중요한 비즈니스에서 잘못된 결정을 유도할 수도 있다.
  • 쉬운 표현을 써야 한다. 복합문장은 이해하기 어려운 경우가 종종 있다. 가능하면 문장은 작게 잘라서 하나의 문장에 하나의 논리만 포함하도록 하는 것이 좋다.
  • 맞춤법이 맞아야 한다. 맞춤법이 틀리면 문서의 내용 및 문서 작성자에 대한 신뢰가 떨어질 수 있다.
  • 읽기 편하게 화면을 구성해야 한다. 화면에 적당한 여백을 두고 자간, 행간을 조절하고, 적절한 그림이나 표를 사용해서 문서를 읽는 사람이 지루해 하지 않고 문서의 내용을 빨리 파악할 수 있도록 해야 한다.
  • 화면 꾸미기에 시간을 허비 하지 않는다.
 
다시 한번 강조를 하지만 개발자는 문서를 잘 작성할 줄 알아야 합니다. 구슬이 서말이라도 꿰어야 보배이듯이 머리 속에 아무리 좋은 정보를 담고 있어도, 이를 문서로 잘 작성할 수 없다면, 고급 개발자는 될 수 없습니다. 꾸준히 문서를 작성하고 읽는 사람으로 부터 평가를 받아야 합니다. 문서를 잘 작성해야 한다고 깨닫는 것이 문서를 잘 작성하기 위한 과정의 시작입니다.

댓글 18개:

  1. 종종 '산출물 작업'을 고객 때문에 어쩔 수 없이 하는 요식 행위로 보는 경우를 볼 수 있다. 이에 대해 꽤 공감할만한 글이 있다: 프로젝트 산출물을 프로젝트 종료 후에 만들고 있나요? 좋은 내용이지만, 자신의 상황과 연결지을 수 없으면 느낌이 약하다. 문서 작업이 필요하다고 느껴서, 문서 작업을 하다가 위 글이 생각나서 문서 일부를 공유해본다. 얼핏 보아선 그냥 말로 해도 될만한 간단한 그림이다. 그러나, 회의를 통해 위 그림 한 장에 그려진 내용..

    답글삭제
  2. 회사에서 문서작성하라는 이야기가 저도 제일 무섭습니다.. ㅠㅠ

    답글삭제
  3. 잘 잘성해야겠군요

    답글삭제
  4. 개발자도 문서를 잘 작성할 수 있어야 한다.

    답글삭제
  5. kkommy님 안녕하세요.
    개발자들은 문서 작성하지 말고 개발하라고 하면 대부분 좋아하죠. ^^

    답글삭제
  6. 공감합니다.
    일전에 "문서 작성 방법"에 대해 정리해서 팀원들에게 나누어 준적이 있는데,
    그때 팀원들 반응이 "너도 관리자 다 됐구나" 뭐 이런 냉소적인 반응이었지요.
    살짝 상처받았던 기억이 납니다 ^^;

    답글삭제
  7. Ray. 전규현님의 글에 트랙백합니다.개발자도 문서를 잘 잘성할 수 있어야 한다. 문서 작업을 좀 많이 해본 - 그리 대단한 건 아닙니다만 - 개발자로서 생각해둔 몇가지 지침을 알려드리고자 합니다. 왜 개발자가 문서를 잘 작성해야 하는지는 Ray님께서 자세히 설명해 주셨고, 또한 트랙백 걸린 영회님의 글도 읽어볼만 합니다. 저는 구체적으로 개발 문서를 작성하는 요령을 이야기해 보고 싶습니다.1. 텍스트 위주로 작성한다.저는 블로그에 글을 쓸데도...

    답글삭제
  8. 헝그리맨님은 팀장이신가보죠? 팀원들이 건방지네요. ^^

    답글삭제
  9. 제가 블로그하는 이유 중의 하나가 작문 연습이기도 하죠. 그런데 생각처럼 잘 안 되네요.

    그리고 제목에 오타 있습니다.
    잘성 -> 작성

    답글삭제
  10. 아리새의펙촉님 안녕하세요. 오타가 있다니 쑥스럽네요. - -; 블로그에 글을 쓸 때 문법을 꼼꼼히 점검하지 못하네요.

    답글삭제
  11. 알면서도 잘 안된다는게 문제죠. 잘 만들려고 노력하다 보면 언젠가는...

    답글삭제
  12.   전규현님의 블로그에서 읽은 포스팅을 배경으로 트랙백 날립니다. 먼저 전적으로 공감하는 전규현님의 글을 읽고 실제 프로젝트 상황에서 요구사항 관리상의 관련 활동에서 가장 기초적이고 끝까지 잃지 말아야 하지만, 그게 쉽지만은 않은 전제조건이 무엇일까 하는 물음에 다음과 같이 4가지로 정리를 해봤습니다.1. 프로젝트의 범위와 목적을 명확하게  엄청엄청 중요한 조건이 아닌가 생각을 합니다. 프로젝트 착수 후, 프로젝트의 ...

    답글삭제
  13. 김성동님 안녕하세요.
    그래서 문서작성기술의 필요성을 인식하는 것이 가장 주요하다고 강조했습니다. 그래야 꾸준히 노력하죠.

    답글삭제
  14. 위대한 다익스트라도 학생을 뽑을 때 말하는 것. 글 쓰는 것을 보고 뽑았다고 들었습니다.

    답글삭제
  15. 태민님 안녕하세요.
    그렇군요.

    답글삭제
  16. 문서작성 아무리 강조해도 지나치지 않죠.
    특히나 소위 짬밥을 먹으면 먹을수록 더 중요해지는게 전체적인 그림(전체 시스템에 대한 이해라고 보시면 될듯^^)을 파악하는 능력과 함께 문서 작업 + 프리젠테이션 능력이 아닐까 합니다.
    역시 문서는? 남에게 보여주기 위한 것입니다.!

    답글삭제
  17. 돌이아빠님 안녕하세요.
    하지만 많은 엔지니어들이 자신이 가지고 있는 정보를 감춤으로써 자신의 가치를 더 높이려하는 경향이 있습니다. 단기적으로는 그런 효과가 있을지 몰라도 결국에는 자신의 미래를 갉아먹는 짓이요.

    답글삭제