프로젝트 문서화는 소프트웨어 제품을 내놓을 때 종종 필요악이 됩니다. 하지만 문서를 버튼 클릭 한 번으로 작성할 수 있다고 상상해 보세요. 사람을 위한 자동화 연재에서, 자동화 전문가 Paul Duvall은 오픈 소스 도구를 이용해 어떻게 UML(Unified Modeling Language), 빌드 다이어그램, ERD(Entity-relationship diagram), 그리고 심지어 사용자 문서까지 생성할 수 있는지 설명합니다.

소 프트웨어 개발 프로젝트에서 문서 쓰기를 좋아한다고 말하는 개발자를 만날 일은 별로 없다. 프로젝트를 떠나거나 늘 외로운 개발자가 되거나 사용자가 한 명도 없기를 바라지 않는 한(프로젝트에 좋은 징조는 아닐 것이다) 소프트웨어의 목적을 다른 사람들에게 알릴 반영구적인 방법이 필요하다. 애자일 선언문의 '종합적인 문서보다는 동작하는 소프트웨어'라는 문장을 문서가 필요없다는 의미로 오해하는 개발자들도 있다(참고자료). 다른 한편으로는 사용자 또는 다른 개발자들에게 불필요한 문서라는 부담을 지울 필요도 없다. 나는 행복할 수 있는 방안을 찾고 있다. 한 번 맞춰보라. 이 글에서 자동화로 프로젝트 문서를 만드는 프로세스를 합리적으로 만들고 문서 작성의 비극을 줄이는 방법을 보여줄 것이다.

본 연재에 대해 개발자로서 우리는 고객의 프로세스를 자동화하기 위해 일한다. 하지만 대부분은 우리 스스로의 개발 프로세스를 자동화할 수 있는 기회를 간과하곤 한다. 더 이상 그러지 않기 위해, 사람을 위한 자동화 연재를 기획하여 소프트웨어 개발 프로세스를 자동화하는 실용적인 사용법들과 성공적으로 자동화를 언제 어떻게 적용하는지 설명하겠다.

내 경험에 비춰봤을 때, 두 개의 핵심 문제 때문에 소프트웨어 개발 문서화가 병들고 있다. 첫 번째는 아무도 그것을 읽지 않을 것이라는 가능성 때문이다. 두 번째로 흔한 문제는 문서 작성 시기가 거의 대부분 지연된다는 것이다. 이 두 개 문제는 서로 관련이 있다. 문서가 현재 있다면 사람들은 그것을 읽으려고 했을 것이다. 문서 생성을 자동화하는 것은 그것을 항상 최신 상태로 유지함으로써 소프트웨어 사용자에게 더 유용하게 만들 수 있다.

물론 문서 작성을 자동화함으로써 다른 종류의 장점도 얻을 수 있을 것이다. 하지만 보통 고통을 유발하는 문서화 작업들을 자동화하는 방법에 초점을 맞추겠다(참고자료를 참조하여 아래 목록에 있는 도구 링크를 참조하라).

• UMLGraph를 사용하여 현재 소스 코드를 기반으로 UML 다이어그램 생성하기
• 스키마스파이(SchemaSpy)를 사용하여 데이터베이스에 있는 테이블과 관계들을 ERD로 생성하기
• 그랜드(Grand)를 사용하여 앤트 빌드 타깃과 그 관계를 빌드 다이어그램으로 만들기
• Doxygen을 사용하여 소스 코드 문서 작성하기
• 독북(DocBook)을 사용해 사용자 문서 만들기

다음과 같은 순서로 설명할 것이다.

1. 각각의 작업을 직접 수행할 때 생기는 이슈들을 설명한다.
2. 아파치 앤트(Apache Ant)를 이용하여 그와 관련된 문서 또는 다이어그램 생성 도구를 사용하는 예제 코드를 보여준다.
3. 코드 예제를 사용하여 만든, 즉 "스크립트로 생성한 문서" 이미지를 보여준다.

본 연재에서 보통 그래왔듯이, 모든 예제는 무료로 사용할 수 있으며 여러분의 프로젝트에 도입할 수 있는 오픈 소스 도구들을 사용하고 있다. 몇몇 도구(예를 들어, UMLGraph와 그랜드)는 그래프비즈(GraphViz) 같은 부가적인 도구를 사용하기도 한다. 이것은 특정 도구가 생성한 .dot 파일을 이용한다.