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

개발자(엔지니어)들이 문서를 잘 작성하지 못한다는 것은 익히 알려져 있는 사실입니다.

 

개발자에게 프로그래밍 실력이 더 중요하지 문서 작성 기술이 얼마나 중요하겠냐?라고 생각하는 사람이 있을 수도 있겠지만, 개발자가 성장할수록 문서 작성 능력의 중요도는 점점 더 커집니다.

 

문서를 잘 작성하지 못하는 개발자는 협업을 하는데 있어서 치명적인 결함을 가지고 있다고 할 수 있습니다.

 

그럼 문서를 잘 작성하는 것은 무엇이고? 문서를 잘 작성하지 못하는 것은 무엇일까요?

잘 작성되지 못한 문서의 특징을 한번 살펴보죠.

 

• 문서의 내용이 쉽게 이해가 되지 않는다. 외계어로 작성된 것 같다.
• 여백 없이 빽빽이 작성되어서 읽는데 너무 피곤하다.
• 문법이 많이 틀려서 내용도 신뢰가 가지 않는다. 주어도 없고 문장의 앞뒤가 전혀 맞지 않는다.
• 주변 얘기만 빙빙돌려서 하고 있고 핵심이 뭔지 잘 모르겠다.
• 내가 관심있는 내용은 없고 작성자의 관심거리만 적혀있다.
• 사용하고 있는 단어들이 너무 전문적이고 어렵다.
• 분량이 너무 많아서 읽기 힘들고 주제 파악이 힘들다.

 

물론 개발자라면 개발에 필요한 핵심문서를 잘 작성할 수 있어야 합니다. 하지만, 이같이 기본적인 문서작성 기술도 없다면, 개발문서라고 해서 잘 작성할 수는 없습니다.

 

"조엘온소프트웨어"의 저자인 조엘 스폴스키는 개발자를 뽑을 때 글을 잘 쓰는 사람을 뽑는다는 원칙이 있다고 합니다. 글 쓰기 능력을 키우는 것은 프로그래밍 실력을 키우는 것보다도 더 어려울 수 있습니다. 그래서 아예 글을 잘 쓰는 사람을 뽑는 것이 더 합리적으로 보이기도 합니다.

 

개발자들은 문서를 잘 작성하지 못한다는 얘기는 어디서나 통하는 말이지만, 특히 우리나라의 개발자들은 단순 주입식 교육 환경 때문에 읽고, 외우는 것은 잘하지만 자신의 의견을 남들에게 쉽고 조리있게 전달하는데는 익숙하지 못합니다. 그렇다고 문서작성을 포기할 수는 없죠. 평생 혼자서 개발할 것이 아니라면 문서는 점점 더 필요하게 되죠. 아니 혼자서 개발을 하더라도 문서를 잘 작성하는 것이 필요합니다.

 

그럼 문서 작성 실력을 키우기 위해서 어떻게 해야 할까요? 역시 훈련이 필요합니다. 단순히 여러 번 작성해 본다고 되는 것이 아니라 제대로 작성하기 위해서 노력해야 합니다. 이제, 문서 작성 실력을 향상하기 위한 몇 가이드를 하려고 합니다. 그 출발점은 다음과 같습니다.

 

"문서작성 기술이 필수 기술이라는 것을 먼저 인식해야 합니다."

 

필요성을 못 느끼면 발전도 없습니다. 그리고 문서를 잘 작성하려면 다음과 같은 것을 고려해야 합니다.

 

• 문서를 작성하는 목적은 내가 일기 위한 것이 아니고 남이 읽기 위한 것이다. 읽는 사람의 눈높이에 맞춰서 적절한 단어를 사용해야 한다.
• 주제를 직설적으로 전달해야 한다. 문서를 읽는 사람은 친절하게 문서를 처음부터 끝까지 다 읽어 줄만큼 한가하지 않다. 주제를 먼저 전달함으로써 문서를 읽는 사람이 문서를 계속 읽을지 말지 결정할 수 있도록 해야 한다.
• 필요한 내용을 쓴다. 문서 작성의 목적을 달성할 수 있도록 문서를 읽는 사람이 기대하는 내용을 충분히 적어야 하며 자신만 관심 있어 하는 필요 없는 내용은 쓰지 않는다. 이런 내용들은 문서의 양만 늘리고 문서의 가치를 떨어뜨린다.
• 사실과 의견을 확실히 구분하여 작성한다. 사실과 의견의 혼동은 수많은 오해를 불러일으키게 된다. 심지어는 중요한 비즈니스에서 잘못된 결정을 유도할 수도 있다.
• 쉬운 표현을 써야 한다. 복합문장은 이해하기 어려운 경우가 종종 있다. 가능하면 문장은 작게 잘라서 하나의 문장에 하나의 논리만 포함하도록 하는 것이 좋다.
• 맞춤법이 맞아야 한다. 맞춤법이 틀리면 문서의 내용 및 문서 작성자에 대한 신뢰가 떨어질 수 있다.
• 읽기 편하게 화면을 구성해야 한다. 화면에 적당한 여백을 두고 자간, 행간을 조절하고, 적절한 그림이나 표를 사용해서 문서를 읽는 사람이 지루해 하지 않고 문서의 내용을 빨리 파악할 수 있도록 해야 한다.
• 화면 꾸미기에 시간을 허비 하지 않는다.

 

다시 한번 강조를 하지만 개발자는 문서를 잘 작성할 줄 알아야 합니다. 구슬이 서말이라도 꿰어야 보배이듯이 머리 속에 아무리 좋은 정보를 담고 있어도, 이를 문서로 잘 작성할 수 없다면, 고급 개발자는 될 수 없습니다. 꾸준히 문서를 작성하고 읽는 사람으로 부터 평가를 받아야 합니다. 문서를 잘 작성해야 한다고 깨닫는 것이 문서를 잘 작성하기 위한 과정의 시작입니다.