외부 문서의 지원이 필요한 코드는 작성하지 마라. 그런 코드는 취약하다. 코드 자체만으로 명료하게 읽히도록 만들어야 한다. Show 코드가 명료해지면 실수할 가능성이 적어지기 때문에, 코드의 품질이 높아지고, 유지보수 비용이 줄어든다. (가독성을 높이는 것이 최대 목표라고 생각해라.) 가끔 자신이 만든 소스를 다른 사람들이 쉽게 알아보지 못하는 것에 대해 쾌감을 느끼는 변태들이 있다. 단점은 그런 변태들과 같이 일하고 싶어하는 사람이 적다는 것이다. 같은 일을 하는 함수다. 어떻게 보이는지 감상해보자. 중요한 것은 짧은 코드를 작성하는 것이 아니라 다른 프로그래머가 봤을 때 쉽게 읽을 수 있고 명확한 코드를 작성하는 것이다. if문의 함정에 조심하라! 내가 권하는 방법은 if문은 가능한 처음부터 사용하지 말라는 것이다. 초보 프로그래머가 쉽게 작성하는 코드는 많은 문제를 if, else문으로 처리하려고 들고 if문 내에 전체 코드를 다 넣으려고 한다. 특히나 if문으로 오류처리를 하면서 전체 코드를 다 집어넣는 경우 처리할 오류가 많아질수록 중첩수준이 깊어진다. 그래서 일단 이론적으로 올바른 입력이 있을때(아무런 오류처리도 필요없을 때)의 코드를 먼저 작성하고 오류처리는 if문으로 나중에 추가하라고 권한다. 불필요한 경우 else문도 절대 사용하지 말것을 권한다. 이것이 올바른 것인지는 모르겠지만 중첩의 깊이가 적을수록 코드를 읽을 때 생각할 것이 줄어든다는 믿음에는 변함이 없다. 보기 좋은 코드의 중요성 구성요소 1. 문서 2. 분할 3. 네이밍 4. 언어의 사용 형태 5. 포매팅 코드의 문서화 주석을 작성해야 하는 이유 : 사용자가 그 코드와 어떻게 연동할 수 있는지 설명하기 위해서 공개 메소드에 주석을 제공하면 1. 코드로는 표현하기 어려운 내용을 자연 언어로 기술할 수 있다 2. 그 메소드의 사용 방법을 담을 수 있다 메타정보를 제공하는 주석 : 코드의 개별적인 기능을 설명하기 보다 코드가 생성된 배경에 대해 설명한다 리팩토링 : 코드를 재구성하는 것 추상화를 더욱 강화하는 방법 1. 필드(멤버 변수)를 캡슐화한다 : 필드를 private 블록에 두고 접근은 게터와 세터를 이용 2. 타입을 일반화한다 : 좀 더 일반적, 범용적 타입을 이용햇 많은 코드에서 활용할 수 있게 한다 코드를 좀 더 논리적인 부분으로 분할하는 방법 1. 메소드를 추출한다 : 덩치가 큰 메소드의 일부를 새로운 메소드로 분리해서 만든다 2. 클래스를 추출한다 : 기존 클래스에서 일부분을 추려내어 새로운 클래스로 만든다 네이밍과 코드 위치를 개선하는 방법 1. 메소드나 필드를 이동시킨다 2. 메소드나 필드의 이름을 변경한다 3. 풀업 : OOP 코드에서 상위 클래스로 이동 4. 풀다운 : 하위 클래스로 이동 프로그램 디자인 (소프트웨어 디자인) : 주어진 기능적, 성능적 요건을 구현하기 위한 아키텍처의 설명서이다 1. 전체 프로그램을 구성하고 있는 서브시스템 : 각 서브시스템 간의 종속성 및 인터페이스, 각 서브시스템 간의 데이터 흐름과 입출력, 전체적인 스레드 활용 모델을 설명하는 부분 2. 서브시스템별 상세 사항 : 클래스 구성, 계층도, 데이터 구조, 알고리즘, 개별 스레드 활용 모델, 에러 처리 방법을 설명하는 부분 나선형 개발 모델 (Spiral Mode) : 요구 분석, 디자인, 구현 단계를 반복적으로 순회하면서 점진적으로 완성해나간다 프로그램 디자인은 각 서브시스템의 구성과 연동 방식을 설명하여 목적하는 요구 조건에 따라 프로그램이 작동할지 판단할 수 있게 해준다. 디자인이 주는 큰 그림이 없으면 세부적인 구현에 몰입되어 중요한 아키텍처적 요소나 목표를 잃어버릴 수 있다 문서화 디자인은 모든 프로젝트 멤버가 상시 참조할 수 있는 공유정보 역할을 한다 디자인의 두가지 원칙 1. 추상화 (abstraction) : 내부 구현과 외부 인터페이스를 분리 2. 재사용 : 기존 코드를 활용, 여러 가지 일반적인 디자인 문제에 적용되는 접근 방법이나 전략을 재활용한다. 코드 재사용은 중복되는 코드가 없어야 한다 재사용이 가능한 코드 1. 과거에 직접 작성했던 코드 2. 동료가 작성한 코드 3. 재직 중인 조직 바깥에 있는 협력 업체에서 작성한 코드 재사용 코드의 구성 형태 1. 독립 함수 / 클래스 2. 라이브러리 : 함수 목록을 제공 3. 프레임워크 : 프로그램의 디자인과 구조의 기반 Big-O 표기법 : 상대적인 성능을 나타낸다. 알고리즘의 실행 소요 시간을 입력 데이터의 크기에 대한 함수로 나타낸 것 알고리즘 복잡도라고도 한다 ex) O(n) : O는 Big-O 표기법, n은 입력 데이터의 크기 문서화에 대해 아무도 말해주지 않는 것들
아무리 문서 작업에 노오력을 쏟아봤자 방향을 잘못 잡으면 소프트웨어의 품질에는 전혀 도움이 되지 않습니다.
튜토리얼, 하우-투 가이드, 해설, 기술 레퍼런스가 바로 그 네 가지입니다. 이 네 가지는 각기 다른 목적이나 기능을 가지고 있고 각각의 작성을 위해서 서로 다른 접근법이 요구됩니다. 이것들이 뭘 의미하는지를 이해하는 것은 문서화의 질을 향상시키는 데에 큰 도움이 됩니다. 서론문서화가 똑바로 되어있지 않으면 소프트웨어가 아무리 잘 만들어져 있더라도 사람들은 사용하지 않습니다. 행여 다른 선택지가 없어서 강제로 그 소프트웨어를 써야 하는 상황이라 해도 제대로 된 문서가 없으면 유저들은 소프트웨어를 당신의 의도와는 전혀 다르거나 비효율적인 방법으로 사용하게 될 것입니다. 대다수의 사람들은 유저에게 좋은 문서가 필요하다는 것을 알고 있고, 좋은 문서를 만들기 위해 노력합니다. 그리고 대부분 실패합니다. 노력이 부족해서 실패하는 경우는 별로 없습니다. 그보다는 노력을 했으나 그 노력의 방향이 잘못되었기 때문에 망하는 경우가 일반적이죠. 이 포스팅을 통해서 필자는 어떻게 하면 문서화를 더 잘 할 수 있는지를 설명하고자 합니다. 무작정 노오력을 하는 것 보다는 제대로 된 방향을 잡을 수 있게요. 올바른 방법은 사실 더 쉬운 방법이기도 합니다. 작성하기에도 더 쉽고 관리도 더 용이하죠. 잘 언급되지는 않지만 문서화를 지배하는 몇 가지 단순한 원칙이 존재합니다. 별로 비밀도 아닌데도 자주 비밀스럽게 묻혀있는 것들이죠. 이 원칙들에 숙달 되기만 한다면 당신의 문서와 프로젝트는 한결 나아질 것입니다. 더 나아가서 당신의 제품과 당신의 팀도 발전하게 될 겁니다. 두고 보세요. 비결문서화는 튜토리얼Tutorial/하우-투 가이드How-to guide/해설Explanation/기술 레퍼런스Technical reference 등 네 가지의 역할 중 하나에 속해야 하며 거기에 알맞는 구조를 가져야 합니다. 각각의 기능은 서로 완전히 다른 접근 방법으로 작성 되어야 합니다. 유저들은 서로 다른 상황과 서로 다른 시점에 이들 문서를 찾게 되기 때문에 대부분의 소프트웨어는 저 네 가지 종류의 문서를 모두 갖출 필요가 있습니다. 문서는 명시적으로 이들 중 한 가지의 구조를 가져야 하고, 다른 종류의 문서들과 명확하게 구분되어야 합니다. 튜토리얼튜토리얼은
비유하자면, 어린 아이에게 요리법을 가르치는 것과 비슷합니다. 하우-투 가이드하우-투 가이드는
요리책에 쓰여진 조리법을 떠올려보세요. 해설 문서해설 문서는
요리의 역사에 대한 기사를 생각해보세요. 레퍼런스레퍼런스는
백과사전 항목을 떠올려 보시면 됩니다. 이러한 구분은 작성자와 독자 양측에게 정보의 향방에 대한 분명한 예측을 가능하게 합니다. 작성자 입장에서는 무엇을, 어디에, 어떻게 써야 하는지에 대한 지침이 됩니다. 그럴싸한 문서를 만들어내기 위해 수많은 정보들과 씨름하는 고통에서 작성자를 구해주는 것이죠. 각 종류의 문서는 각각 단 하나의 목적만을 가지고 있으니까요. 사실, 명시적으로든 암시적으로든 이 네 가지 중 하나로 분류되지 않는 문서는 관리하기 어렵습니다. 각각의 문서는 다른 문서들과 완전히 다른 요구사항을 가지고 있기 때문에, 이러한 분류 체계를 유지하지 못하는 문서를 관리하는 것은 마치 한 번에 사방팔방으로 줄을 모두 당기려는 것과 같습니다. 일단 이 분류 체계를 이해하게 되면, 이미 존재하는 문서들을 분석하고 어떻게 그 문서들을 향상시킬 수 있는지 이해하는 데에도 아주 유용한 지식이 될 것입니다. 프로젝트 문서변경사항change logs이나 기여 정책contribution policy이나 기타 프로젝트에 관련된 이런 저런 문서들은 어떤 분류에 해당하는지 아마 의문이 들텐데요, 정답은 저 문서들이 그 중 어디에도 해당하지 않는다는 것입니다. 엄밀히 말해서 저 문서들은 ‘소프트웨어’ 자체에 대한 문서가 아니라 프로젝트에 관한 문서들이기 때문입니다. 저것들은 그냥 소프트웨어의 다른 것들과 섞이지 않는 선에서 적당한 곳에 적당히 보관하면 됩니다. 프로젝트 문서에 관한 위 사항을 기억해두고 이제부터 네 가지 문서 종류 각각에 대해 살펴보도록 하겠습니다. 튜토리얼튜토리얼은 어떤 프로젝트를 달성하는 데까지 독자를 단계적으로 이끌어가는 강좌입니다. 이를 통해 이 프로젝트로 무언가를 달성하는 방법과 순서를 초보자에게 보여줄 수 있습니다. 이는 전체적으로 학습 지향적인 문서이며, 특히 프로젝트 자체에 대해 배우기보다는, 프로젝트를 통해 무언가를 이루는 방법을 배우는 데에 중점을 두고 있습니다. 당신은 선생님이 되어, 책임을 가지고 학생들을 가르쳐야 합니다. 당신의 설명을 따라서 학생들은 어떤 목표를 이루기 위한 일련의 행동을 실행하게 됩니다. 학생들의 행동과 목표는 당신이 결정해야 합니다. 하지만 목표를 결정하는 것은 쉬운 일이 아닙니다. 제시되는 목표는 충분히 의미있으면서도, 완전 초보자까지도 달성할 수 있음직한 것이어야 합니다. 아이에게 요리를 가르친다고 가정해 봅시다 어떤 요리를 가르칠 것인지는 사실은 별로 중요한 게 아닙니다. 진짜 중요한 것은 아이가 요리의 즐거움을 깨닫고 자신감을 갖게 되는 것, 더욱 도전하고 싶은 마음을 심어주는 것입니다. 소프트웨어를 사용하는 것은 요리를 하는 것처럼 기능적인 작업입니다. 지식이긴 하지만 이론적인 지식이라기보다는 실제로 겪어봐야 하는 종류의 지식이죠. 우리는 이런 류의 새로운 기술이나 재주를 처음 배울 땐 늘 우선 직접 해보는 데서 시작하곤 합니다. 중요한 점은, 튜토리얼을 모두 완료한 학습자가 나머지 다른 문서들과 해당 소프트웨어 자체를 이해할 수 있는 위치에 선다는 것입니다. 대부분의 소프트웨어 프로젝트는 튜토리얼이 아예 없거나 있더라도 아주 구질구질합니다. 튜토리얼이란 건 '학습자’를 '사용자’로 탈바꿈시켜주는 문서입니다. 튜토리얼이 후지거나 아예 없다는 건, 새로운 사용자가 프로젝트에 유입되는 것을 가로막는 장벽이 됩니다. 좋은 튜토리얼을 작성하는 것은 아주 어렵습니다. 초보자에게도 유용해야 하고, 따라가기에도 쉬워야 하며, 의미있게 잘 짜여져있어야 하니까요. 튜토리얼을 잘 쓰는 방법직접 시도해 보면서 배우게 하세요우리는 뭐든 처음에는 직접 해보면서 배웁니다. 옹알이나 걸음마처럼요. 소프트웨어 튜토리얼에서 학습자는 무언가를 직접 실행해야 합니다. 튜토리얼에서 요구하는 행동들은 가능한 여러가지 도구와 조작을 접하도록 해주는 것이 좋습니다. 처음에는 단순한 것을 만들고 점진적으로 복잡한 것들을 다루게 해야 하고요. 일단은 어쨌든 시도를 하게 만드세요초보자의 첫 걸음은 손을 잡고 이끌어주는 걸음마여도 충분합니다. 마찬가지로 초보자에게 처음 알려주는 방법이 ‘경험자라면 절대 하지 않을’ 방법이거나 ‘올바르지 않은’ 방법이어도 괜찮습니다. 튜토리얼은 모범 사례 설명서가 아니니까요. 튜토리얼의 중요한 점은 학습자가 여정을 시작하게 하는 데에 있는 것이지 그들을 목적지에 데려다 주는 데에 있는 것이 아닙니다. 튜토리얼은 반드시 잘 작동해야 합니다.선생님으로서 해야 할 일 중 하나는 초보자의 자신감을 복돋아주는 것입니다. 소프트웨어, 튜토리얼, 학습 과정 자체에 대한 자신감도 그렇고, 튜토리얼이 제시하는 과제를 달성할 수 있다는 자신감까지 불어넣어 주어야 합니다. 친근한 조언, 일관성 있는 언어 사용, 자료들을 통한 논리적 진행 등 자신감을 복돋아주기 위한 많은 방법들이 있습니다. 하지만 이런 방법들보다 우선 가장 중요한 점은 제시한 과제가 반드시 제대로 동작해야 한다는 것입니다. 학습자는 당신이 시킨대로 어떤 행동을 했을 때 반드시 당신이 말 한대로의 효과를 확인할 수 있어야 합니다. 학습자의 행동이 이상한 결과나 오류를 만들어낸다면 튜토리얼은 망한 것입니다. 당신 탓이건 아니건 그런건 중요하지 않습니다. 옆에서 학생을 보고 있다면 그 자리에서 어떻게든 해결해 줄 수 있겠지만 학생이 그저 혼자서 튜토리얼 문서를 읽고 있는 거라면 그럴 수가 없습니다. 따라서 그런 일이 일어나지 않도록 미리 미리 대비를 해야 합니다. 물론 말처럼 쉬운 건 아닙니다만. 유저가 결과를 바로 확인할 수 있도록 하세요.학습자가 하는 모든 행동은 아무리 사소하더라도 이해할 수 있는 뭔가를 달성하는 것이어야 합니다. 혹시 학생이 이해가 안 가는 뻘짓을 두 페이지씩 따라 해야 겨우 결과를 확인할 수 있다면 그건 좀 너무한거죠. 모든 행동의 효과는 가능한 빠르고 분명하게 눈에 보여야 합니다. 물론 행동과 결과의 연관성도 명확하게 드러나야 하구요. 또한, 튜토리얼의 각 섹션의 결론, 튜토리얼 전체를 아우르는 결론은 반드시 의미있는 성과여야 합니다. 튜토리얼을 반복할 수 있게 만드세요.튜토리얼은 반드시 반복이 가능해야 합니다. 그렇게 만드는 게 쉽진 않지만요. 사람들은 튜토리얼에 여러가지 운영체제와 도구를 통해서 찾아오고, 각 개인이 가진 경험도 천차만별입니다. 게다가 같은 유저라고 하더라도 사용하는 프로그램이나 자원들은 매번 조금씩 달라져있을 가능성이 큽니다. 그 어떤 유저가 시도하더라도 튜토리얼은 항상 정확히 동작해야 합니다. 안타깝지만 튜토리얼이 그렇게 잘 작동하는 것을 확인하기 위해서는 정기적이고 세심한 테스트가 필요하겠죠. 추상적인 개념보다는 구체적인 단계에 집중하세요.튜토리얼은 정확한 행동과 결과를 바탕으로 구체적인 내용을 담고 있어야 합니다. 추상적인 내용을 소개하고 싶은 유혹은 아주 강렬합니다. 추상화야말로 대부분의 컴퓨터 공학의 힘의 원천이니까요. 하지만 모든 학습의 과정은 구체적이고 특정한 부분으로부터 점차 일반적이고 추상적인 방향으로 진행되어야 합니다. 학습자가 구체적인 내용에 대해 충분히 곱씹어볼 기회를 갖기도 전에 추상화의 이점을 설파하려 드는 것은 잘못된 교습 방법입니다. 필요한 최소한의 설명만을 제공하세요.굳이 학습자에게 별로 필요도 없는 지식을 모조리 설명하려 들지 마세요. 물론 논의의 지평을 넓히는 것은 중요한 일이지만, 굳이 튜토리얼에서 그럴 필요는 없습니다. 그런 내용들은 그냥 학습의 방해물에 불과합니다. 필요 최소한의 설명이 딱 적당합니다. 튜토리얼에서 직접 설명을 하는 대신 어디 다른 문서에 있는 설명을 링크로 제공하세요. 오직 사용자가 해야 하는 단계에만 집중하세요.튜토리얼은 당장 해야 하는 작업에만 집중할 필요가 있습니다. 당신이 방금 소개한 명령어가 다른 수많은 옵션을 가지고 있을 수도 있겠죠. 혹은 어떤 API 에 접근하는 수많은 다른 방법들이 있을 수도 있구요. 하지만 그딴 게 무슨 상관이 있겠습니까. 지금 당장 튜토리얼을 진행하는 데 필요한 것도 아닌데. 하우-투 가이드하우-투 가이드는 현실적 문제를 단계별로 해결하는 방법을 설명합니다. 하우-투 가이드는 특정한 목표를 달성하기 위한 안내서입니다. 예를 들어 ‘웹 폼을 만드는 법’, ‘3차원 데이터셋을 도면으로 그리는 법’, ‘LDAP 인증을 활성화 하는 법’ 같은 것들이죠. 하우-투 가이드는 목표 지향적인 문서입니다. 비유하자면, 무언가를 먹기 위해서 어떤 식재료를 요리하는 방법을 설명하는 조리법과 비슷합니다. 조리법은 명확하게 정의된 목표가 있고 특정한 질문을 다룹니다. 이 문서는 어떠한 목표를 달성하기 위한 과정을 설명하는 것이며, 이 문서를 읽는 사람이 이미 기본적인 지식을 갖추었을 거라고 전제할 수 있습니다. 하우-투 가이드는 튜토리얼과는 완전히 다릅니다. 하우-투 가이드는 튜토리얼이 대상으로 할 만한 진짜 초보자로서는 떠올리지도 못 할 만한 질문에 대한 해답을 제시합니다. 하우-투 가이드에서는 독자가 어느 정도의 기본적 지식과 이해를 가지고 있다거나, 이미 기본적인 방법과 도구 활용법을 알고 있다고 가정하고 설명할 수 있죠. 하우-투 가이드 문서는 대체로 꽤 잘 갖춰져있는 경우가 많습니다. 작성하기에도 쉽고 재밌는 편이죠. 하우-투 가이드를 잘 쓰는 방법일련의 단계를 제시하세요하우-투 가이드는 순서대로 따라야 하는 단계별 목록을 제시합니다(튜토리얼과 흡사합니다). 굳이 아주 초보적인 부분보다는 적당하다고 생각되는 부분을 시작점으로 선택할 수 있습니다. 하우-투 가이드는 신뢰할 수 있어야 하지만 튜토리얼처럼 반드시 반복 가능해야 하는 견고한 구조까지는 필요하지 않습니다. 결과물에 집중하세요하우-투 가이드는 실용적인 목표에 집중해야 합니다. 그 외의 다른 것은 모두 부차적인 문제입니다. 튜토리얼에서와 마찬가지로, 과도한 설명은 지양해야 합니다. 문제를 해결하세요하우-투 가이드는 반드시 특정한 문제나 질문에 대한 해답을 제시해야 합니다. 이 문서는 “ㅇㅇㅇ을 하는 방법” 이니까요. 이 점이 바로 하우-투 가이드가 튜토리얼과 차별화되는 부분입니다. 하우-투 가이드를 읽는 독자는 자신이 하고자 하는 게 무엇인지는 이미 짐작하고 있습니다. 다만 구체적인 방법을 모를 뿐이죠. 튜토리얼에서처럼 당신은 독자가 해당 문제를 해결하기 위해 무엇을 알아야 하는지를 결정할 책임이 있습니다. 개념을 설명하지 마세요하우-투 가이드는 뭔가를 설명하지 않습니다. 그런 종류의 논의를 하기 위한 무대가 아닙니다. 하우-투 가이드에서는 단순히 행동을 나열하면 됩니다. 만약 중요한 설명이 필요하다면 해당 설명에 대한 링크를 제공하세요. 어느정도의 유연성을 허용하세요하우-투 가이드는 같은 일을 하기 위한 여러가지 다른 방법들에 대해 유연한 태도를 가져야 합니다. 여러 비슷한 경우들에 대해 제시된 내용이 어떻게 적용이 가능한지 유저가 알 수 있을 정도, 혹은 비슷한 다른 시스템이나 환경에서 어떻게 이 방법을 적용할 있는지 알 수 있을 정도면 충분합니다. 너무 특정한 상황에서만 들어맞는 문서는 정확히 동일한 상황이 아니면 쓸모가 없겠죠. 내버려 두세요완벽한 것 보다는 실용적인 것이 중요합니다. 튜토리얼은 완성도가 높고 처음부터 끝까지를 제대로 설명해야 하지만 하우-투 가이드는 그럴 필요가 없습니다. 하우-투 가이드는 시작와 끝을 적당히 정해도 됩니다. 주제와 관계된 것이 있다고 해서 굳이 그 것들을 모조리 언급할 필요도 없습니다. 내용이 너무 빵빵한 하우-투 가이드는 유저에게 빠른 해결책을 제공하지 못합니다. 적절한 이름을 붙이세요하우-투 가이드의 제목은 이 문서가 무엇을 설명하고 있는지를 정확하게 드러내야 합니다. ‘클래스 기반 뷰를 만드는 방법’ 은 좋은 제목입니다. '클래스 기반 뷰 만들기’는 좀 애매하네요. '클래스 기반 뷰’라는 제목은 영 별로입니다. 레퍼런스기술 레퍼런스는 실제로 작동하는 메커니즘과 그 운용 방식에 대한 기술적인 설명입니다. 레퍼런스는 오직 설명만 합니다. 레퍼런스가 설명하는 내용이 클래스나 함수, API, 기타 등등 코드 그 자체이기 때문에 문서의 구조는 코드의 구조를 따르게 됩니다. 또한 레퍼런스는 함수, 멤버 변수, 속성, 메소드 같은 것들의 목록을 나열하고 그것들을 사용하는 방법을 제시합니다. 레퍼런스는 정보 지향적입니다. 기술 레퍼런스는 사용법을 묘사하기 위한 예제를 포함할 수도 있지만 기본적인 개념을 설명하거나 공통적인 작업을 달성하는 방법을 설명하기 위한 예제여서는 안됩니다. 레퍼런스는 간결하고 정중해야 합니다. 요리법에 관한 비유를 다시 들자면 레퍼런스는 어떤 식재료에 대한 백과사전 항목과 비슷합니다. 해당 식재료의 성분, 기원, 효능과 화학적 구조, 조리법등을 담고 있죠. 레퍼런스에는 이 기능을 어떻게 사용하는지에 관한 기초적 설명이 꼭 포함되어야 합니다. 예를 들면 특정 클래스를 어떻게 인스턴스화 하는지, 어떤 메소드를 어떻게 호출하는지, 어떤 함수에 무언가 매개변수를 넘길 때 반드시 주의해야 할 점은 무엇인지 등등. 이런 점들이 레퍼런스와 하우-투 가이드를 구분짓는 차이점입니다. 소프트웨어의 정확한 사용법을 설명하는 것(레퍼런스)은 특정한 목적을 달성하기 위한 방법을 보여주는것(하우-투 가이드)과는 전혀 다릅니다. 세상엔 레퍼런스 말고 다른 종류의 문서라는 게 존재한다는 걸 상상도 못하는 개발자들도 있습니다. 그들은 이미 그들의 소프트웨어를 이해하고 있으며, 어떻게 사용하는지도 알고 있습니다. 그들은 다른 사람들에게 필요한 것도 오직 그런 기술적인 정보들일거라고만 여깁니다. 레퍼런스 문서도 보통 잘 작성되어 있는 편입니다. 심지어 자동으로 생성할 수도 있습니다(결과물이 항상 좀 허술하긴 하지만). 레퍼런스를 잘 쓰는 방법문서 구조는 코드에 기반해서 결정하세요레퍼런스 문서의 구조를 코드베이스와 동일하게 만들면 사용자는 코드와 레퍼런스 문서를 함께 참조할 수 있습니다. 또한, 이렇게 하면 관리자들도 쉽게 문서화 과정에서 빠진 부분이나 갱신이 필요한 부분을 발견할 수 있게 됩니다. 일관적인 표현을 사용하세요레퍼런스 문서는 다른 사전들처럼 구조, 어조, 형식등을 항상 일관성 있게 사용해야 합니다. 오직 설명만 하세요레퍼런스 문서에 요구되는 유일한 기능은 바로 가급적 명확하고 완전한 설명입니다. 그 외의 다른 것들(해설, 논의, 조언, 추측, 의견 등)은 문서를 활용하기도, 유지보수하기도 어렵게 만듭니다. 혹시 필요하다면 설명을 위한 적절한 예제를 제공하세요 레퍼런스 매뉴얼에 기본적인 소프트웨어 사용법을 넘어서, 특정한 목적을 이루기 위한 응용법을 설명하고 싶은 유혹을 떨쳐내세요. 개념을 설명하고 싶은 욕심이나 개발과 관련된 사항을 논의하고 싶은 충동도 이겨내야 합니다. 대신 적절하게 하우-투 가이드와 해설 문서, 튜토리얼 문서들에 대한 링크를 제공하세요. 정확하게 작성하세요이 문서에 포함된 설명들은 반드시 최신화된 정확한 내용이어야 합니다. 설명 문서와 실제 동작 사이에 존재하는 모순 유저의 꼭지를 확 돌게 만들고 말 것입니다. 해설 문서해설과 논의는 특정한 주제를 명확히 하거나 주의를 환기합니다. 이런 것들은 문서가 커버하는 주제의 범위를 넓히는 역할을 합니다. 해설 문서는 이해 지향적입니다. 해설 문서는 어떤 면에서는 논의 문서라고도 할 수 있습니다. 이 문서들은 소프트웨어 자체에서 한 발짝 물러나서 더 넓은 시야, 혹은 기존과 다른 관점에서 소프트웨어를 바라볼 수 있게 해 줍니다. 여가 시간에 취미로 코드를 읽는 것 보다는 해설이나 논의를 읽는 게 일반적으로 덜 이상해보이겠죠. 이런 종류의 문서가 명시적으로 생성 되는 경우는 드뭅니다. 대신 문서나 코드 여기저기에 파편화된 해설들이 흩어져있곤 하죠. 가끔 해설 섹션이 존재하는 경우가 있긴 하지만 그런 경우에도 보통 '해설’이라는 제목이 아니라 대충 '배경 설명’이나 ‘비고’ 등의 제목이 붙어있고 제대로 된 해설이나 논의 문서로 기능하지 않기 일쑤입니다. 논의 문서는 생각보다 쓰기 쉽습니다. 누군가의 질문에 대답하는 게 아무래도 빈 종이에 무언가에 대한 설명을 써내려가는 것 보다는 간단하니까요. 특정한 목표를 달성하기 위한 방법(하우-투 가이드)이나, 사용자가 배우길 바라는 주제(튜토리얼), 작동 방식에 의해 정의되는 내용(레퍼런스)…등을 제외한 주제 중에서 당신이 한 문서에 담기 적당하다고 생각하는 내용들을 넣는 곳이 바로 해설/논의 문서입니다. 따라서 간혹 논의 문서가 다루는 주제는 좀 생뚱맞을 수도 있습니다. 해설 문서를 잘 쓰는 방법맥락을 제공하세요해설 문서는 배경과 맥락을 제공하는 곳입니다. 예를 들면 ‘Django를 통해 제어되는 웹 폼’ 이라던지 ‘Django CMS와 검색에 관하여’ 같은 것들이 되겠죠. 또한, 현재의 어떤 것이 왜, 어쩌다가 이렇게 된 것인지 (설계 단계의 결정 때문이었다거나, 어떤 역사적 이유가 있다거나, 기술적 제약 때문이라거나 등등) 그 이유를 설명할 수 있는 곳이기도 합니다. 대안과 의견들을 논의하세요해설 문서에서는 여러 대안들이나 다각도의 접근을 고려할 수 있습니다. 예를 들어 Django 배포에 관한 문서라면 여러가지 웹 서버를 사용하는 선택지들에 대해 고려하고 평가하는 등의 내용이 있을 수 있겠죠. 논의 문서는 서로 반대되는 의견들을 저울대에 올릴 수도 있습니다. 예를 들면 ‘테스트 모듈을 패키지 디렉토리 안에 넣을까 밖으로 빼야 할까’ 같은 것들이죠. 무언가를 지시하거나 기술적 레퍼런스를 제공하지 마세요해설 문서는 다른 문서들이 제공하지 않는 내용을 제공해야 합니다. 해설 문서는 유저에게 무언가를 하는 방법을 지시하거나 설명하는 곳이 아닙니다. 기술적인 설명을 제공하는 곳도 아니구요. 이런 내용들은 이미 다른 문서들이 해치운 부분이니까요. 이런 문서 구조에 관해서분류가 왜 이렇게 애매하죠?이렇게 명확한 분류 체계가 있음에도 불구하고 각 문서들이 애매하게 분류되고 서로의 영역을 자꾸 침범하는 데에는 이유가 있습니다.
이렇게 각각의 영역들이 조금씩 겹치기 때문에 구분이 혼란스럽고 서로 섞여 버리곤 하는 거죠. 그러다보니 이 네 가지가 정확히 분류된 좋은 예를 찾기는 어렵습니다만, 꽤 많은 문서들이 이 네 가지 분류를 각기 다른 기능으로 인식하고 있다는 것은 어렵지 않게 확인할 수 있습니다. Django(Django의 예전 버전들은 이러한 분류들을 명시적으로 사용하지는 않았었습니다)나 Django CMS 같은 몇몇 프로젝트들은 이 분류를 전면적으로 적용하고 있습니다. 두 프로젝트 모두에서 이러한 분류 방식은 가치를 입증해냈죠. 분석에 대해서이 글에서 제시하는 문서화에 대한 분석은 다년간의 문서 작성 및 유지보수 경험과, 어떻게 하면 문서화를 더 향상시킬 수 있는지에 대해 고민하면서 보낸 많은 시간들에 기초하고 있습니다. 또한 이 글은 여러 분야에서 회자되는 원칙들에도 기초하고 있습니다. 예를 들어 튜토리얼에 대한 내용은 교육학의 기초적인 개념을 차용하고 있죠. 학습자와 선생을 배치하고, 소프트웨어 활용법을 마치 구체적인 작업을 하는 단계를 거침에 따라 일반적이고 추상적인 원칙과 개념을 익힐 수 있는 작업처럼 취급합니다. 문서화 작업하기문서 작업자들의 가장 큰 두통거리 중 하나는 그들이 해야 하는 일이 뭔지 정확히 예측 할 수가 없다는 것입니다. 글을 쓰고 또 쓰지만 그럴 수록 흡족하게 글을 쓰기는 어렵다는 것만 깨닫게 되죠. 이 글에서 제시한 구조는 명확한 분류와 구분으로 그 의문점들을 해소해줍니다. 이 방식은 문서를 작성하고 유지보수하기 편하게 만들어 줍니다. 게다가 사용하거나 탐색하기에도 더 편리하죠. 여전히 문서화가 자동으로 되진 않습니다만, 이제 더 이상 뭔가 어색한 문서 분류나 내용의 애매한 범위, 대체 문서에 어떤 내용이 들어있어야 하는지, 이런 문서는 어떤 스타일을 적용해야 하는지와 같은 문제를 가지고 씨름할 필요가 없습니다. 뭘 써야 할 지, 어떻게 써야 할 지, 그리고 어디에 써야 할 지가 훨씬 명확해졌죠. 이는 사용자에게 더 나은 서비스를 제공하게 해줍니다. 이제 사용자는 소프트웨어를 사용하는 어떤 단계에서든 그 시점에 가장 적절한 종류의 문서를 확인할 수 있기 때문입니다. 명시적/암시적으로 이 네 가지 종류의 문서를 작성해 두는 것은 더 많은 사용자를 소프트웨어로 모아들이고 유지할 수 있게 해줍니다. 이 사용자들은 잘 분류된 문서를 통해 소프트웨어를 더욱 효율적으로 활용할 수 있게 되죠. 궁극적으로 모든 소프트웨어 개발자들이 꿈꾸는 목표가 바로 이 것이겠죠. About the Divio Expert seriesOur experts really do deserve the name. Between them they have decades of Django development experience; the depth and breadth of the expertise we are able able to offer is world-class. They include core developers of Django, django CMS and other
notable projects, and the architects of very large systems such as the Divio Cloud infrastructure. 작성자 : Daniele Procida
|
프로그래밍 코드 문서화 하기 좋은 방법
저작권 © 2024 ihoctot Inc.
