2011년 6월 12일 일요일

개발자는 글을 잘 쓰지 못한다?


개발문서 작성은 항상 개발자를 따라다니면서 괴롭힌다.


체계적으로 개발을 하려면 개발문서를 적절하게 작성해야 한다고 다들 이론적으로는 알고 있다. 실제 그렇게 하지 않아도 이를 부정하는 개발자는 그렇게 많지 않다.

물론 핑계는 있다. 워낙 바빠서 문서를 만들 시간이 없다. 다 아는 내용이라서 문서를 작성하는 것은 시간 낭비다.

그럼에도 불구하고 회사에서 문서 작성을 강제로라도 시키면 개발자들은 MS Word를 열어 놓고 코딩할 때 처럼 진도가 나가지 않는다. 이때 주로 하는 얘기가 "머리 속에는 잔뜩 있는데 글을 잘 작성하지 못해서 문서를 작성하기 어렵다"라는 것이다.

이렇게 되다보니 문서만 작성하라고 하면 거부 반응을 보이게 된다.

하지만 이는 개발문서 작성을 피해보려는 핑계에 불과하다.
개발문서를 작성하는데 있어서 의외로 "글쓰는 재주"는 별로 필요하지 않다.

개발자들이 가장 흔히 작성하는 개발문서는
스펙과 설계 문서이다. 사용자 메뉴얼을 쓴다면 "글쓰는 재주"가 아주 많이 필요할 것이다. 하지만 스펙과 설계 문서를 작성하는데는 글쓰는 재주보다는 내용이 더 중요하다. 스펙과 설계 문서의 독자는 대부분 프로젝트 관련자와 개발자이기 때문에 잘 적힌 문장이 아니더라도 필요한 내용만 적히면 문제가 없다.

결론을 말하면 개발자들은 글쓰는 재주가 없어서 개발문서를 잘 작성하지 못하는 것이 아니고
분석을 못해서 "스펙"문서를 작성하지 못하고 설계를 못해서 "설계"문서를 잘 작성하지 못하는 것이다. 

문서는 분석과 설계의 결과물일 뿐이다. 스펙문서는 SRS Template을 보면 적어도 어떠한 내용이 적혀야 하는지 약간의 도움을 받을 수 있다. 설계문서는 Template이나 툴이 중요하다기 보다는 창의력을 발휘하여 설명할 수 있어야 한다.

문서가 잘 작성되었는지의 판가름은 문서작성자 외의 다른 개발자들이 이 문서를 받아서 일을 할 수 있나 보는 것이다. 물론 본인이 혼자서 분석, 설계, 구현을 하는 경우라도 상세도만 약간 줄이면 되며 내용은 빠짐없이 적어야 한다.

다른 사람이 보고 일을 하려면 화려하고 멋진 문장보다는 정확한 내용을 전달하기만 하면 된다. 기본적으로 주어, 목적어 등을 빼먹어서 애매하게 만드는 일은 없어야 한다. 또한 내용도 정량적으로 기술할 수 있어야 한다. 애매하게 "빨라야 한다"라든가 "편리해야 한다"등의 표현은 절절하지 않다. 이정도는 글쓰는 재주가 없어도 조금만 신경쓰면 되는 내용이다.

과거에 잘작성된 문서를 받아서 개발을 해본 경험이 몇번이라도 있으면 본인이 그러한 문서를 작성해서 다른 사람에게 넘기는 일은 어렵지 않을 것이다. 하지만 우리나라에서는 이러한 개발 문화가 없기 때문에 이런 경험을 가진 개발자를 보기란 정말 어렵다. 그래서 스스로 분석, 설계 방법을 터득해야 하는데 정말로 어려운 일이 아닐 수 없다. 간접적인 경험으로 인터넷의 글이나 책을 보곤하는데 이를 통해서는 너무 많은 정보를 접해서 핵심을 놓치고 오히려 방해가 되곤 한다.

결론은 원칙을 잘 생각하는 것이다. 자신이 작성한 문서를 다른 개발자가 보고 개발을 할 수 있게 해야 한다는 것을 잊지 말자 물론 개발뿐만 아니라 QA, Tech pub, Marketing, Sales 등 모든 부서가 일을 할 수 있어야 한다.

글재주가 없어서 문서를 잘 작성하지 못하는 것이 아니라는 것을 받아드리면 개발문서에 한단계 다가간 것이다. 일단 긍정적인 마음으로 시작하는 것이 중요하다. 그러면 메모 한장이라도 작성하는 것이 더 빠르게 개발하는 길이라는 것을 차츰 알게 될 것이다.


댓글 11개:

  1. 개발자 코드의 변수 선언을 보면 답이 나옵니다.
    영어를 잘해서 좋은 변수명을 선언하는 게 아니라, 내용을 잘 알면, 사전에서 찾으면 되겠지요.
    결국 내용을 모르면서 코딩도 하는 게 아닌가 싶습니다.
    그런데 심지어 문서라니요^^

    그래도 계속 연마하면 좋아지는데, 쉽게 포기하고들 말더군요... 가랑비에 옷 젖듯이... 일신우일신 해야 하는데...

    답글삭제
  2. 글 잘 봤습니다.
    SE 공부하면서 가끔씩 느끼는 부분이었는데, 설명을 잘 해주셨네요 ^^
    하지만 본문에 언급한 "글쓰는 재주"가 논문 쓸 때 드러나게 마련이죠 ㅠㅠ

    답글삭제
  3. 안녕하세요. dtoa님

    논문은 읽는 대상이 개발문서보다 비교가 안될 만큼 넓기 때문에 문서의 전체 구조나 문장도 좀더 잘 적어야 합니다. 이런 과장에서 잘 훈련된 엔지니어라면 개발문서를 좀더 잘 적을 수 있겠네요.

    답글삭제
  4. 디밥님 안녕하세요.

    동감입니다. "연마"... 꾸준히 해야 느는 법이죠.

    답글삭제
  5. 안녕하세요. 다시한번 다짐을 하게되는 글이네요
    이번에 이직을 하게되어 인수인계기간에 있습니다. 포스팅 보면서 문서의 소중함을 알고 제 나름대로 문서를 작성해왔었는데,
    그게 지금 빛을 발하네요. 문서만으로 다른사람이 충분히 운영할수있게 되었습니다 ㅎㅎ 감사합니다 마지막으로 본문에 '상세도만 약간 줄이 면 되면'에서 되며가 아닌가 하고 조심스럽게 말해봅니다.
    더위조심하세요~~

    답글삭제
  6. 안녕하세요? 글쓴 내용과는 다른 답글이긴 한데.. 혹시 블로그에 페이스북 댓글 달 생각은 없으신가요? 몇군데 달아놓은 곳 보니(제 블로그 포함) 편하긴 편하더라구요. 누가 누군지 알기도 쉽고 :)

    답글삭제
  7. 아래 달아 봤습니다. "좋아요" 버튼은 안생기네요. - -;

    답글삭제
  8. 좋아요 버튼 다는건 또 따로 있어요. ㅎㅎㅎ

    답글삭제
  9. 음.. 초보개발자들을 위해서 SRS Template 나
    개발개념서 라던가 이런것들을 공유해주시는건 어떨까요?

    한번 해보고는 싶지만 개략적인 틀도 없는 상황에서는 뜬구름 잡는 느낌이라서 말이죠 ^^;

    답글삭제
  10. 안녕하세요. 구차니님
    Google에서 SRS Template으로 검색하면 수두룩하게 나옵니다. 샘플로 많이 나옵니다. 물론 영어로 되어 있습니다.
    하지만 별로 도움이 안됩니다.
    타이거우즈 스윙 동영상을 아무리 봐도 나의 스윙에는 별로 도움이 안되는 것과 비슷합니다. 스스로 연습을 많이 하고 코치의 코칭을 받아야 늘죠.
    샘플이나 Template를 보는 것보다 가이드 하는 책을 보고 직접 써보면서 프로젝트를 여러차례 직접 해보는 것이 중요합니다.
    SRS를 써서 다른 개발자에게 개발하라고 주면 개발할 수 있어야 제대로 작성한 겁니다. 그런 마음가짐으로 쓰시면 됩니다. 쉽지는 않습니다.

    답글삭제