가장 좋은 문서화의 방법은 무엇인가를 써보는 것이다. 많은 프로그래머가 이를 빠뜨린다. 여기 문서화를 해야만 하는 두 가지 이유를 설명하겠다.
문서화를 통해 설계 문서를 작성할 수 있다. 문서화의 가장 좋은 시기는 무엇을 해야할 지를 생각하는 동안이며, 한 줄의 코드도 작성하기 전이다. 프로그램이 어떻게 움직여야 할지를 자연어로 서술하다 보면, 프로그램이 무엇을, 어떻게 하도록 할 것인가와 같은 고차원적인 질문으로 생각이 발전할 것이다. 이렇게 함으로써 훗날에 있을지도 모르는 작업의 양을 줄일 수 있다.
문서화는 코드의 품질에 대한 홍보이다. 많은 개발자들이 빈약하고, 불충분하며 문법적으로도 엉성한 문서를 만듦으로써, 사용자의 요구에 대해 무관심하고 무지하다는 인식을 심어주게 된다. 반면에 좋은 문서는 지적이고 프로의식이 있다는 인상을 주게 된다. 만약, 경쟁상대가 있는 프로젝트라면 최소한 잠재적인 사용자들이 프로그램을 제대로 보지도 않고 선택의 대상에서 제외하지 않도록 문서를 잘 만들어야 한다.
이 HOWTO는 실제적이지만 기술적인 작문 코스를 위한 것은 아니다. 여기서는 문서를 작성하고 표현하는데 필요한 형식이나 도구에 초점을 맞추어 설명한다.
유닉스와 오픈-소스 커뮤니티에게는 오랜 전통으로 내려오는 강력한 문서화 도구가 있음에도 불구하고, 여러가지의 다른 형식이 과다하게 존재하는 것은 문서화가 단편화되어 가는 경향이 있고, 사용자가 일관된 방법으로 브라우징하고 인덱싱 하는 것이 어렵다는 것을 의미한다. 여기서는 사용법과 강점 그리고 일반적인 문서화 양식의 약점을 요약하여 설명한다. 그리고 훌륭한 문서화 방식을 권고할 것이다.
여기서는 오픈-소스 개발자들 사이에서 널리 사용되는 문서화 표현 형태를 설명한다. 'presentation'은 (폰트 변경과 같은)문서의 외양을 명확하게 제어하는 마크업이며, 'structural'은 (절의 구분이나 강조 태그 같은)문서의 논리적인 구조를 설명하는 마크업이다. 그리고 'indexing'은 사용자가 전체 문서 집합에서 관심있는 자료를 확실하게 찾을 수 있도록 주제와 관련된 문서 집합에서 찾아내는 과정을 의미한다.
유닉스에서 이어져온 초기 'presentation' 마크업이며 가장 일반적인 형식이다. man(1) 명령은 페이져와 아주 오래된 검색도구를 제공한다. 이미지나 하이퍼링크, 인덱싱은 지원하지 않는다. 인쇄를 위한 포스트스크립트 렌더링은 매우 잘된다. HTML로는 표현할 수 없다.(필요하다면 텍스트로만 가능하다.) 관련도구는 리눅스 시스템에 이미 설치되어 있다.
man 페이지 형식은 명령어의 요약이나 숙련된 사용자의 기억을 되살려주는 간단한 참조용 문서로는 나쁘지 않다. man 페이지는 복잡한 인터페이스와 많은 옵션을 가지려는 경향 하에서 삐걱거기 시작했다. 그러므로 이를 이용하여 많은 교차-참조를 갖는 문서를 관리하려고 한다면 (하이퍼링크의 지원이 없는 상황에서) 완전히 실패할 것이다.
1993-1994 이후로 웹이 나타나면서 HTML의 사용이 증가하였다. 마크업은 부분적으로 'structural' 이고 대부분은 'presentation'이다. 어떤 브라우져에서도 브라우징이 가능하며, 이미지와 하이퍼링크도 잘 지원한다. 내장된 인덱싱 도구는 기능이 제한적이지만, 좋은 인덱싱 및 검색엔진 기술이 존재하고 현재 널리 쓰이고 있다. 인쇄를 위한 포스트스크립트 표현도 잘 된다. HTML 도구는 현재 전 세계적으로 사용되고 있다.
HTML은 여러가지 종류의 문서화에 매우 융통성 있고 적합한 방식이다. 실제로, 융통성이 무척이나 크다; 많은양의 마크업이 문서의 structure보다는 presentation을 표시 함으로 인하여 자동적으로 인덱싱하는데 문제가 생기면 man 페이지 형식을 공유하기도 한다.
Texinfo는 자유 소프트웨어 재단(FSF)에서 사용하는 문서화 방식이다. Texinpo는 강력한 Tex 포맷팅 엔진 위에 올라가는 매크로의 집합이다. 대부분이 'structural' 정보이고, 일부가 'presentation'과 관계되어 있다. Emacs나 독자적인 info라는 프로그램으로 브라우징 할 수 있다. 하이퍼링크를 잘 지원하지만 이미지에 대한 지원은 하지 않는다. 인쇄와 온라인 형식을 위한 인덱스를 둘다 지원한다. Texinfo 문서를 설치하면 시스템의 모든 Texinfo 문서를 리스팅하는 'dir'문서에 위치가 자동적으로 추가된다. 포스트 스크립트를 완벽하게 지원하며, HTML로도 사용할 수 있다. Texinfo 도구는 대부분 의 리눅스 시스템에 내장되어 있으며, Free Software Foundation 에서 찾을 수 있다.
Texinfo는 설계가 잘 되어있고 인쇄용 책이나 크기가 작은 온라인 문서에는 유용하게 사용할 수 있지만, HTML과 마찬가지로 양서류과에 속한다. 즉, 마크업이 부분적인 'structural'과 'presentation'으로 구성 되어 있으며 'presentation' 부분은 렌더링을 할 때 문제가 있다.
DocBook은 SGML을 기반으로 하는 크고, 정성들여 만든 마크업 형식이다. (XML보다 최근 버전이다.) 앞에서 소개한 표현 방식들과는 달리, 모두 'structural'을 표현하는 마크업으로만 구성되어 있고 'presentation'은 없다. 이미지, 하이퍼링크를 완벽하게 지원하며, HTML로의 렌더링이나 인쇄를 위한 포스트스크립트도 잘 지원한다.( 인쇄의 질은 도구의 발전에 따라 증진될 것이다.) 이와 관련된 도구와 문서는 DocBook website에서 찾을 수 있다.
DocBook은 크고, 복잡한 문서 작성을 위한 훌륭한 방식이다. DocBook은 기술 매뉴얼의 작성과 이들을 다양한 출력형태로 렌더링하기위해 특별히 설계되었다. 이것의 단점은 복잡도와 도구들이 완전히 성숙하지 않았다는 것(비록, 빠르게 발전하고는 있지만)과 소개하는 수준의 문서가 부족하고 (아주 빈번하게) 매우 혼란스럽다는 점이다.
2000년 7월, 주요한 오픈-소스 프로젝트 그룹(GNOME, KDE, 자유소프트웨어 재단, 리눅스 문서화 프로젝트, 오픈-소스 발기그룹을 포함하는)의 대표가 모여서 수뇌 회의를 캘리포니아의 몬터레이에서 개최하였다. 회의는 문서화와 문서교환의 표준형식을 연구하고 확정해서 보다 풍부하고 통합된 형태의 문서화 형식이 발전할 수 있도록 하는데 그 목적이 있었다.
구체적으로, 회의 참석자 모두가 동일하게 인정한 사항은, 설치하는 즉시 시스템의 모든 문서 인덱스에 통합되어, 모든 문서가 단일한 인터페이스와 유닛 단위의 검색을 통해 브라우징이 가능하도록하는 문서화 패키지를 만드는 것이다. GNOME과 KDE는 단계적으로 이미 그러한 방향을 채택하고 있었으며, 이를 위해서는 'presentation' 보다는 'structural'의 마크업 표준이 필요하다는 것을 이미 이해하고 있었다.
회의에서는 명백한 문서화 경향을 승인하였다. 주요한 오픈-소스 프로젝트는 이미 문서화 형식으로 주로 Docbook을 적용하고 있거나 이미 적용하였다.
참가자들은 문서의 인덱싱을 지원하는 'Dublin Core' 메타데이타 형식(디지털 자료의 인덱싱과 관련하여 도서관 관리자들이 개발한 국제 표준)를 사용하기로 결정하였다. 여기에 대한 세부사항은 계속 해결해 나가고 있으며, 아마도 결과물은 DocBook 문서에, Dublin Core 메타데이터의 내장을 지원하기 위한 마크업이 추가되는 것으로 나타날 것이다.
방향은 명백하다; 인덱스 태깅과 Dublin Core 메타데이터를 기반으로하여 Docbook 문서의 자동 인덱싱을 지원하는 보조 표준과 함께 Docbook을 사용하는 것이다. 여기에는 여전히 빠진 사항이 몇 가지 있지만 그것들은 언젠가는 채워질 것이다. 예전의 'presentation' 기반 마크업을 쓸 날들은 얼마 남지 않았다.(이 문서도 2000년 8월에 Docbook으로 이전하였다.)
따라서, 새로운 오픈-소스 프로젝트를 시작하는 이들이 DocBook을 주 형식으로 해서 시작한다면, 변화를 앞질러 가면서 나중에 닥칠 고약한 변환 작업을 피해 갈 수 있을 것이다.