Thoughts2013.12.23 17:35

개발자는 대체로 문서 작업을 "오버헤드"로 받아들이는 경향이 있습니다. 품질 관리자 가운데는 이런 경향에 섭섭함을 토로할 분도 계시겠습니다만, 이건 엄연한 사실입니다. 개발자 가운데, 문서를 요구하는 관리자와 언쟁을 벌여본 경험이 없는 사람은 없을 겁니다. 


http://www.challengefuture.org/news/707


개발자에게 한가지 불행한 일은, 누군가는 그렇게 생산된 문서를 본다는 사실입니다. (편의상 문서 소비자라고 해 봅시다.) 그러니 문서화를 완전히 피할 방법은 없지요. 


문서 소비자에게 불행한 일은, 개발자가 생산한 문서 가운데 상당수에 적힌 내용이 실제 소프트웨어와 다르다는 사실입니다. 그런 상황이라면 소프트웨어를 만든 사람의 역량을 의심하게 되는 것도 무리는 아니지요.


이 불행은 무엇에서 비롯된 것일까요? 저는 '가치'에 대한 오해에서 비롯되었다고 봅니다. 개발은 고객에게 반드시 전달되어야 하는 가치를 만드는 행위입니다. 그렇다면 문서는 어떻습니까? 고객에게 보여주어야 하는 문서라면, '문서화'의 목적 또한 '고객에게 가치를 전달하는 것'이 되어야 마땅합니다. 내부 개발자들만이 공유할 문서라면요? 그럴 때는 이야기가 좀 달라집니다. 개발자들만이 볼 문서라면, 개발자들에게 최선의 가치를 전달할 수 있는 형태의 문서가 되어야 맞습니다. 관리자에게 보고할 문서라면요? 관리자들이 개발 진행상황을 쉽게 이해할 수 있도록, 최대한 간략화되고 개조식으로 정리된 문서가 되어야 맞을 겁니다. 그것이 관리자가 요구하는 '문서의 가치'이니까요. (관리자에게 가장 중요한 것은 '의사결정'임을 상기합시다.)


자. 그렇다면 우리는 비교적 쉽게, 문서화를 하는 데 있어 지켜야 할 원칙들을 뽑아낼 수 있을 것 같습니다. 문서화 작업에 있어서 우리가 지켜야 할 원칙들은, 의외로 우리가 개발할 때 지키는 원칙들과 비슷합니다. 


1. 단순성 (Simplicity) - 쓸데 없는 이야기를 하지 않는다. 


문서를 만들 때 중언부언 하지 않습니다. 가치에 반하는 것은 없앱니다. 개발자 내부적으로만 공유할 문서에 참여자들의 사인을 전부 받을 필요는 없습니다. 그런건 이슈 관리 시스템의 동료 검토 기능을 활용하면 됩니다. 개발자들만 볼 문서에 API의 상세 스펙을 넣을 필요는 없습니다. 그런건 JavaDoc에나 넣으면 됩니다.  단순하게 만들면 정보 중복이 줄어들고 관리 비용이 하락합니다. 필요한 내용만 넣고, 쓸데 없는 건 다 빼버리세요. 그런건 누가 요구할 때나 추가해 넣으면 됩니다 (규칙 5 참고).


2. 무결성 (consistency) - 소프트웨어의 실제 상태에 부합한다.


문서는 언제나 소프트웨어의 실제 상태에 부합해야 합니다. 고객이 어떤 사람이건 간에, 실제 상태에 부합하지 않는 문서는 언제나 실패한 문서입니다. 실패한 문서를 만들지 않는 몇 가지 방법이 있습니다. 첫 번째는 필요한 순간에 문서를 만들어 전달하고 해당 문서에 유효기간을 두는 것입니다 (규칙 4 참고). 두 번째는 개발자로 하여금 언제나 문서 창을 열어놓고 시스템을 변경할 때 마다 문서까지 변경하도록 요구하는 것입니다. 세 번째는 개발자가 언제나 주석에 가장 정확한 내용을 반영하도록 권하고, 필요할 때마다 주석에 적힌 내용을 갈무리해 문서를 만드는 것입니다. (세 번째 가이드라인을 따르는 문서가 JavaDoc같은 것입니다.) 


3. 독자 지향 (reader-oriented) - 문서를 읽을 사람을 고려한다. 


문서를 읽을 사람이 용역을 준 갑이라면 클래스 다이어그램이 필요할 것입니다. 그러나 고객이 시스템 사용자라면 클래스 다이어그램까지 그려진 문서를 주는 것은 과도합니다. 그런 경우에는 웹에 '사용자 가이드'와 'API 명세서'만 올려놓으면 충분합니다. 누가 문서의 고객인지를 생각하고, 거기 맞는 문서를 만드세요. 10명도 안되는 팀에서 다섯명 정도의 개발자들만이 돌려볼 문서라면, 아예 문서화를 포기하는 것도 생각해 보세요. 그런 팀에서라면 문서화 보다 잡담을 장려하는 쪽이 훨씬 나을지도 모릅니다. (그 팀의 진정한 목적이, 고객에게 '훌륭한 소프트웨어'라는 가치를 전달하는 것이라면 말이에요.) 


4. 적시성 (timeliness) - 문서가 필요한 시점을 고려한다. 


프로토타이핑이 진행된 결과로 이미 돌아가는 시스템이 있는 상태인데 굳이 설계 문서를 만들어서 클래스 다이어그램을 넣을 필요는 없습니다. 그런 것은 고객의 요구가 없는 한, 쓸데 없는 짓입니다. 문서가 여섯달 뒤에 필요한데, 지금부터 문서를 작성하는 것도 쓸데 없는 짓입니다. 그렇게 되면 문서의 무결성을 확보하기 위해 너무 많은 수고를 들여야 합니다 (규칙 2 참고). 언제 문서가 필요한지를 보고, 그에 맞는 문서화 계획을 세우세요.


5. 요구 지향 (demand-oriented) - 문서에 대한 고객의 요청을 고려한다. 


요청이 있다는 것은 고객이 문서를 통해 얻고자 하는 가치가 있다는 뜻입니다. 고객의 요구를 추정하다보면 문서에 너무 많은 내용을 담게 됩니다. 한 번에 완벽한 문서를 만들기 보다는, 고객의 요구를 받아들여 필요한 문서를 작성하는 것이 바람직합니다. 위키는 이런 용도에 적합한 시스템입니다. 위키에 기록된 사항만 언제나 무결하게 정리해 놓으면, 고객의 요구에 즉시 응답할 수 있습니다. 새로운 요청은 위키에 먼저 반영하여 고객의 반응을 살피고, 고객이 만족할 때 공식 문서로 변환할 수 있습니다. 그러니, 필요하지도 않은 문서를 만드는 데 너무 많은 시간을 쓰지 마세요. 


그리고 이 모든 원칙들이 너무 복잡하다면, 이것만 항상 생각하세요. '이 문서는 고객(문서를 읽을 사람)에게 어떤 가치를 주게 될까?' 이것만 기억한다면, 과도한 문서화의 함성에서 조금은 벗어나게 될 수도 있습니다.



저작자 표시 비영리 변경 금지
신고
Posted by 이병준

소중한 의견, 감사합니다. ^^

Extremely Agile/General2009.01.16 14:00
흔히 시스템을 만들 때 요구사항을 먼저 수집하곤 합니다. 그러나 떄로는 실제 사용자로부터 요구사항을 수집하지 않은 상태에서 (혹은 수집할 수 없는 상태에서) 시스템을 만들어야 하는 경우도 있습니다. 특히 새로운 프로그램을 만드는 경우에 그런 일이 많이 벌어집니다.

실제 사용자로부터 요구사항을 수집할 수 없거나, 수집하지 않은 상태에서 시스템을 만들어야 하는 프로젝트는, 대략 다음 중 하나의 경우에 해당합니다.

1. 연구용 프로젝트
2. 납품이 가능할지 알 수 없는 상태에서 진행되는 프로젝트
3. 혁신적 프로젝트

연구용 프로젝트는 보통 연구자의 필요에 의해 시작되고 진행되기 떄문에, 연구자 자신이 실제 사용자가 되기도 합니다. 그런 측면에서 보자면 "요구사항을 알 수 없어도" 적어도 연구자 자신의 필요에 부합하는 시스템은 나오게 마련입니다. 제 짧은 소견에 비추어 보자면, 많은 오픈소스 프로젝트들은 이 범주에 듭니다. 이런 범주에 드는 시스템은 공개되는 순간 비슷한 관심사를 가지고 있는 많은 동료 연구자들의 지지를 받게 마련이고, 데드라인이라는 제약에서 한 걸음 떨어져 있는 경우가 많아 비교적 느긋하게 요구사항 변화를 통제할 수 있습니다.

혁신적 프로젝트는 보통 시장을 선도할 목적으로 시작되는 프로젝트인데, 운이 좋으면 굉장히 많은 잠재적 사용자들을 고용(?)해서 시작할 수 있습니다만(큰 회사인 경우에 그렇죠) 그렇지 않을 경우에는 프로젝트에 관계된 사람들이 시장의 요구를 예측해서 진행해야 합니다. 어느 쪽이건 간에, 가급적 빠른 시간 내에 내부/외부 사용자들을 접촉해서 피드백을 받기 시작해야 합니다. 그렇지 않으면 프로젝트 후반부에 요구사항 변경과 씨름하느라 일이 좀 힘들어지죠. 혁신적 프로젝트라는 것이 이전 프로젝트의 결과물에 기반한 경우에는 이전 사용자들로부터 수집한 많은 이야기들이 새로운 프로젝트의 밑거름이 될 수 있어서 좀 낫겠습니다만, 그런 경험이 없는 프로젝트라면 더더욱 조심하는 것이 좋습니다.

가장 난감한 프로젝트 유형은 납품이 가능할지 알 수 없는 상태에서 진행되는 프로젝트입니다.

가령 A라는 회사가 B라는 고객이 조만간 '이런 저런 시스템'을 BMT를 통해 구매할거라는 소문을 들었다고 합시다. A라는 회사는 '이런 저런 시스템'을 만들어 본 경험이 있는 회사는 아닌데, '이런 저런 시스템과 비슷한 시스템'을 만들어 본 경험은 있는 회사입니다. B라는 고객은 '이런 저런 시스템'에 꽤 큰 돈을 들일 가능성이 높은 회사라, A사의 경영진은 곧 '이런 저런 시스템'을 만들기 위한 프로젝트 팀을 꾸립니다.

문제는, 이 때 부터 '이런 저런 시스템'에 대한 추측과 '이런 저런 시스템'을 사용할 사용자에 대한 추측이 진행된다는 점입니다. 개발자들은 (1) 이런 요구사항이 나중에 어마어마한 CUSTOMIZATION 요구로 다가올 수 있다는 점과 (2) 계약이 불발날 경우에는 자신들이 만든 코드가 백업 테이프 어딘가에 처박혀 먼지를 뒤집어 쓰게 될 수도 있다는 점을 알고 있기 때문에, 가능한한 그런 일을 피하고자 하게 마련입니다.

이 때 부터 소위 Software Engineering의 여러가지 원칙들이 시험대에 오릅니다. "과도한 Generalization은 좋지 않다"같은 원칙이 제일 먼저 공격을 받습니다. 요구사항을 정확히 알수 없는 상황에서 개발자들은 본능적으로 "모든 코드를 최대한 확장 가능하게 만들"려 애쓰게 됩니다. 언뜻 보면 디자인 패턴(Design pattern)을 통한 개발에 모든 개발자들이 맹목적으로 달려들기 때문에 상황이 개선되고 있는 것 처럼 보이기도 합니다만, 나중에 보면 애초에 만들려던 '이런 저런 시스템' 대신 '어디서 많이 본 시스템', 그것도 마치 '미들웨어의 냄새가 강하게 풍기는' 시스템이 만들어지게 되는 일이 왕왕 생깁니다.

(이런 일이 벌어지고 있는지를 확인하는 가장 간단한 방법은 프로젝트 관리 차트에 '기능(feature)'의 이름 대신 추상적인 SW Engineering 용어들이 적히고 있는지를 보는 것입니다.)

이런 시스템은 '알 수 없어서 발생하는 리스크'를 전부 회피했기 때문에 'CUSTOMIZATION 하기 좋은 시스템'으로 보일 수도 있습니다만, 소위 '구매자의 마음을 끄는 기능'이 없어서 외면을 받기도 합니다. 구매자의 입장에서 보면, '가치를 생산하기 위해서는 반드시 CUSTOMIZATION을 해야 하는' 시스템이 달갑지만은 않을 테니까요.

물론 시스템을 개발한 사람 입장에서는 '빠른 CUSTOMIZATION'을 강점으로 내세워 홍보를 하면 그런 단점은 커버할 수 있지 않겠느냐고 생각할 수도 있겠습니다만, 문제는 "고객과의 소통이 이루어지지 않은 상태에서 generazation을 하기 위해 내렸던 결정들이 반드시 옳을거라는 보장을 할 수 없다"는 점입니다. 나중에 요구사항에 맞지 않아서 구조 자체를 다 뜯어고쳐야 한다면 그것도 난감하기는 마찬가지라는 이야기죠.

이런 상황이라면, 애자일을 하건 워터폴을 하건 아마 마찬가지일 거에요.

* * *

앞선 글에도 적었었습니다만, 세상 어디를 가나 이런 사정은 마찬가지입니다. 적고 보니 '소통'이 중요하다는 이야기를 한 셈인데, '소통'은 리스크를 드러내 준다는 점에서 의미가 있습니다. 요구사항을 알기 위해서 '소통'을 그렇게 열심히 하는 이유는, 가급적 모든 리스크를 빨리 드러내 주어야 계속되는 플래닝 과정이 좀 더 의미있는 결과를 내놓을 가능성이 높아지기 때문입니다.

어제 100분 토론에서 미네르바 아저씨 이야기를 듣다보니, 적어도 그가 '공익'에 한가지 기여를 했다는 점은 분명해 보이더군요. 바로, 이 사회의 리스크를 남김없이 보여주었다는 점이죠. 한 명의 인터넷 스타의 글에 휘둘릴 정도로 취약한 경제구조를 가지고 있다는 점과, 그런 글에 신경증적 반응을 보일 정도로 너그럽지 못한 행정부/사법부/입법부를 가지고 있다는 점.

앞으로 주식투자는 최대한 보수적으로 해야 할 것 같아요.ㅋㅋ
신고
Posted by 이병준

소중한 의견, 감사합니다. ^^

  1. [가짜대통령 이명박 사형 결정 전문] 미ㄴㅔ르바? : 官error안봐??

    [百姓有過 在여一人]<論ㅓ ㅛ曰>

    대통령 스스로가 법을 존중하고 준수하지 않는다면,
    다른 공직자는 물론,
    국민 누구에게도 법의 준수를 요구할 수 없는 것이다.
    <관습헌법? 대통령(노무현) 탄핵 결정 전문> / 가짜대통령 이명박 사형 결정 전문!
    / 관습헌법사항 한 줄조차 몰라서~? 미네르바에게 무슨 법의 준수를 요구하겠답시고??

    의법, 무효대통령! 위헌대통령! 위법대통령! 불법대통령! 사기대통령! 대통령직장물대통령! 사이비대통령! 비합법대통령! 부적법대통령! 가짜대통령! 이명박을 사형으로 처단하라!~@!!
    dead line(2009.02.09.)day
    [명령章!] 이명박을 사형으로 처단하라!~!!.hwp / 이명박 운명 : 대한민국 대운
    대역죄인대통령 치하의 국민들은 다 죄인~!!

    2009.01.18 19:08 신고 [ ADDR : EDIT/ DEL : REPLY ]

Extremely Agile/General2008.08.07 10:08
제품을 개발할 때, 그 제품에 탑재될 기능을 흔히 필수 기능(mandatory features), 선형 기능(linear features), 감동 기능(delighter) 등으로 구분하곤 합니다.

필수 기능은 제품에 반드시 탑재되어야 할 기능, 즉 제품을 시장에 내놓으려면 반드시 들어가야 하는 기능이고,  선형 기능은 많이 들어가면 들어갈수록 고객의 만족도가 늘어나는 기능입니다. 감동 기능은 고객이 기대하지는 않는 기능입니다만, 일단 그런 기능이 있다는 것을 알면 감탄해 마지 않을만한 기능, 기꺼이 그 기능을 위해 지갑을 열만한 기능을 일컫습니다.

최근에 모니터/키보드/마우스 공유기가 필요해서 어떤 제품들이 있는지 인터넷을 뒤져서 좀 살펴봤었습니다. 과거에는 PS2 방식의 공유기가 대세였습니다만, 요즘은 USB 키보드와 마우스가 많아지는 만큼, USB 공유기도 등장하고 있습니다. 필수 기능이 PS2에서 USB쪽으로 이동하고 있다는 증거입니다.

이런 공유기에서 선형 기능은 아마도 공유할 수 있는 모니터/키보드/마우스의 개수일 것입니다. 공유 포트가 많아지면 많아질수록 고객의 만족도는 증가합니다. 물론 그에 비례해서 가격도 증가하기 때문에 고객의 만족도가 이 경우에는 반드시 선형적으로 상승한다고 보기는 좀 어려울 수도 있습니다. 하지만 이렇게 생각해보죠. 고객의 만족도가 증가하면 고객은 그 기능을 위해 기꺼이 지갑을 열고 돈을 지불하게 될 수 있습니다. 그러니 제품을 개발할 때 선형 기능에 대해 생각해 보는 것은 반드시 필요하죠.


사용자 삽입 이미지

그렇다면 만족 기능들로는 어떤 것을 생각해 볼 수 있을까요? 벨킨이라는 업체에서 내놓은 공유기 중 한 모델은 제품을 세워서 놓을 수 있도록 배려하고 있을 뿐 아니라 (공간을 덜 잡아먹습니다) 다른 제품들보다 미려한 외관을 자랑합니다. (최근에는 디자인 적인 요소가 감동 요인으로 등장하는 경우가 늘고 있습니다.) 거기다 이 제품은 여벌의 USB 포트를 제공해, 컴퓨터간에 공통의 USB 장비를 공유할 수 있도록 하는 기능도 제공합니다. USB프린터, USB 메모리 등이 이런 범주에 들 수 있겠죠. 잘만 써먹으면 USB 메모리를 통해 WIndows와 Linux간에 데이터를 아주 손쉽게 공유할수도 있습니다. ㅋㅋ

그런데 이것 말고 다른 감동 요인은 없는 걸까요?

제 책상에는 두 대의 모니터가 있습니다. 한 모니터는 Windows 머신에 연결되어 있고, 다른 한 모니터는 Linux 머신에 연결되어 있습니다. 두 모니터를 동시에 봐야 하기 때문에, 공유기로 연결하더라도 모니터는 연결할 필요가 없습니다. 오직 키보드와 마우스만을 공유해야 하기 때문에, 처음에는 Synergy라는 소프트웨어를 깔아서 키보드와 마우스를 공유하려고 했었습니다.

그런데 문제가 있더군요. 제 컴퓨터들에서는 어쩐 일인지 이 프로그램이 너무 느리게 돌아가는 겁니다. ㅋㅋ Synergy의 가장 큰 장점은, 키보드와 마우스가 두 개의 컴퓨터 사이에 Seamless하게 연동될 수 있도록 만드는 것입니다. 마우스가 윈도우 화면의 가장자리로 이동하면 그 포인터가 자동적으로 Linux 쪽 화면으로 이동하고, 키보드 제어도 자동적으로 그쪽으로 넘어갑니다. 너무 편하죠.

하지만 일반적인 공유기를 사용하면 이런 장점을 누릴 수 없습니다. 모니터를 공유기로 연결하지 않으면 두 화면을 동시에 볼수는 있을텐데, 키보드나 마우스 제어를 다른 컴퓨터로 옮기려면 단축키를 누르거나 공유기의 버튼을 눌러줘야만 합니다.

그렇다면, Synergy가 가지고 있는 기능을 제공하는 공유기가 있다면, 그것이 감동 요인이 될 수 있지 않을까요? 물론 별도의 프로그램을 깔아야 할 수도 있겠고 공유기의 가격도 올라갈 수 있겠습니다만, 두 모니터로 보는 화면이 마치 한 화면처럼 통합될 수 있다는 점에서 (운영체제가 다르고 시스템도 다름에도 불구하고!) 아주 좋은 공유기가 될 수도 있을텐데 말이죠. 저는 아직 이런 제품을 못 찾았습니다. 직접 만들어볼까도 생각해봤는데, 아시다시피 제가 HW쪽으로는 아는게 없어서 말이죠.

신고
Posted by 이병준

소중한 의견, 감사합니다. ^^