효과적인 소프트웨어 문서를 적는 방법

『Documenting Software Architectures』를 읽고 정리, 추가 한 포스트입니다.

호랑이는 죽어서 가죽을 남기고, 개발자는 문서를 남긴다. 

Why? 왜 문서화 해야하나?

개발자로서 협업을 하다 보면 항상 마주치는 현실이 있다. 

이건 왜 이렇게 짜셨나요? 

이렇게 설계한 이유는 무엇인가요? 

commit log를 보세요. 

히스토리에 대해 알고 싶어요. 

어디서 볼수 있나요? 

wiki를 보세요. 

wiki에 어디로 가야하나요? 

XXX page에 맨 아래쪽에 나와 있어요. 

여기 wiki내용은 code에 반영된 것과 다른데요? 

wiki 작성할 시간이 없어요. 

바빠서 작성을 못했네요.

인수인계를 할 때뿐만아니라 일상 실무에서도 많이 일어나는 개발자들 간의 커뮤니케이션 내용이다. 많은 개발자들이 히스토리나 아키텍쳐에 대해 알고 싶어하지만 없거나 정확하지 않은 내용이 있기 부지기수이다. 그러다보니 전래동화나 구전처럼 내려져 오는 이야기들이 문서를 대체하곤 한다.

왜 XXX기능은 YYY에서만 동작하죠?

그건 철수님께 물어보시면 아실거에요.

ABC기능이 왜 configuration이 8로 되어 있을까요?

그건 3은 적합하지 않아서 8로 설정했어요.

3이 적합하지 않다는 것에 대한 문서가 있나요?

그건 제가 테스트 해본 내용이에요. 문서는 작성하지 않았어요.

끔찍한 일임에 틀림없다.

What? 어떤것을 문서화 해야하나?

소프트웨어를 개발 혹은 논의하면서 주장했거나 상상했거나 혹은 칠판에 초안을 적어놓은 모든 것(이상적인 방향)까지 문서화 해야한다. 이런것들이 모이면 아키텍쳐가 설계되는데 정한 여러가지 결정적인 요소들이 기록되게 되고, 왜 아키텍쳐가 이렇게 되었는지에 대한 해답이 된다.

매우 간단한 소프트웨어 시스템이 아닌 다음에야, 소프트웨어 아키텍쳐(프레임워크의 아키텍쳐든 라이브러리의 아키텍쳐든)는 한마디로 설명하기 어렵기 마련이다. 또한, 매우 훌륭한 소프트웨어 아키텍쳐가 있다고 하더라도 이해하기 어렵거나 의미를 전달하기 어려울 때, 즉 문서화가 잘 안되어 있다면 해당 소프트웨어를 사용하는 사람들이나 개발하는 사람은 방향성을 잃기 마련이다.

특히 Kubernetes, Spinnaker, Kafka 등 Opensource software 생태계에서는 Document의 중요성은 두말할 필요가 없을 것이다. Github의 해당 software의 readme.md와 공식홈페이지의 Document를 읽어보고 소프트웨어가 나아가고자 하는 방향성에 대해 공감하고 이해를 하지 못한다면 opensource의 contributing은 나침판을 잃은 사막의 여행자와 다름없다.

How? 어떻게 문서화 해야하나?

1. 읽기 쉬운 문서를 작성한다.

읽는 사람 관점에서 쉬운 문서를 작성해야 한다. 예를 들어 외부인이 보는 문서에 불필요한 내부 전문용어와 같은 것들은 문서를 읽고 빠르게 이해하는데 큰 장애물이 된다.  그리고 작성자가 문서를 조급하게 쓴다면 머릿속에 떠오른 순서대로 문서를 작성하게 된다. 이는 독자가 파악하기 쉬운 구조가 아니다. 보통은 소프트웨어의 실행의 흐름에 따라 작성했을 때 읽기 수월 할 것이다.

2. 불필요한 반복을 피한다.

정보는 종류별로 반드시 한군데에만 기록해야한다. 그래야 문서를 활용하기 편하고 무엇보다 유지보수에 드는 노력이 급감한다. 정보를 확인할때 반복(duplicate)된 정보가 있을 경우, 특히 두 정보가 상이할 경우 독자는 패닉에 빠지게 된다.

3. 모호함을 피한다.

소프트웨어 문서를 읽었을 때, 여러 의도로 해석될 수 있는 상황이라면 문서가 잘못된 것이다. 예를 들어 동그라미 1개에서 나온 선이 네모 1개를 가리키고 있는데 그 선은 삼각형으로 되어 있다고 하자. 과연 그 선은 무엇을 뜻하고? 동그라미는 무엇인가? 객체인지? 클래스인지? 프로세스인지? 선은 상속을 뜻하는지 동기화인지? 알수가 없다. 그러므로, 가능한 독자가 표기법의 의미를 파악하기 쉽게 해주기 위해 기호에 대한 범례를 표시하여 한가지 뜻으로만 이해할 수 있도록 해야한다.

4. 표준체계 문서양식을 따른다.

표준 문서 체계를 정하고, 그 체계에 따라 독자들이 읽도록 유도해야한다. 표준을 따르면 독자는 특정정보를 빠르고 정확하게 찾을 수 있다. 또한 정보의 완결성 규칙도 준수 할수 있기 때문에, 문서를 적는사람 입장에서도 한결 수월해 진다.

5. 근거를 남긴다.

의사 결정의 결과를 문서화 할때는 결과 뿐만 아니라 결과를 선택하는 과정에 대해서도 명확히 기록하여 왜 그런 근거가 되었는지 기록한다.

6. 최신내용을 담되 앞서나가지 않는다.

소프트웨어를 설계하는 과정을 거치다 보면 의사결정 과정에서 다시 생각해보거나 수정하는 일이 빈번하다. 곧 뒤집힐 결정을 반영하여 문서에 적는 것은 낭비이다.

7. 목적에 맞게 작성됐는지 검토한다.

문서에 담고자 했던 정보가 정상적으로 들어갔는지 확인 해보고, 실제 독자에게도 문서를 소개시켜서 양식을 준수하고 있는지 확인 해야한다.

어떤 문서가 좋은 소프트웨어 문서일까?

그렇다면 어떤 문서가 좋은 문서이고 그러한 문서는 어디서 찾아 볼 수 있을까? 

우리가 흔히들 개발을 하면서 보는 여러 문서들이 있다. Pivotal의 Spring boot document, Boot strap의 component document 등. 우리가 개발하고 있는 가까운 곳에 훌륭한 문서들이 존재하고 있다. 

Apache http server 2.4 Document의 목차

상기 스크린샷은 apache http server 2.4 버젼의 document이다. 상기 document를 읽는 독자(개발자)는 대부분 기존에 apache server을 사용하던 사람일 것이고, 그들은 2.4 이전 version 을 사용 중일 것이다. 이 때 필요한 document는 새로운 version에는 어떤 기능이 들어갔는지, 어떻게 업그레이드하는지가 가장 궁금할 것이기에 가장 앞에 목차를 두었다고 볼 수 있다.

Apache http server 2.4 Compiling and Installing 페이지

아파치 서버 설치내용에 대한 절차와 목차도 명확하다. 우측에는 각 설치단계별 수행방법에 대해서 절차대로 카테고리화 하였고, 좌측에는 각 단계별 설치사항에 대해 SAD(Software Architecture Document) 형식에 맞게 작성하였다.

그리고, 마지막으로 검은색 상자의 글씨는 shell command라는 것은 그 어느 개발자가 보아도 알 수 있을 정도로 명확하다.

의견

일상 업무가 바쁘고 일정에 쫓기다보면 항상 document를 최신버젼으로 update를 못할 때도 있다. 나도 그렇다. 하지만 항상 document를 적는것에 대해 자각하고 있어야 한다고 생각한다. 틀린 길을 가고 있다는 것을 자각하지 못하는 것 만큼 위험한 일은 없기 때문이다. 

Document 작성은 개발자에게 개발과 같이 흥미로운 일은 절대 아니다. 그러나, 우리는 하나의 software를 함께 개발하고 함께 사용한다. 이에 따라, 개발자가 누구에게나 쉽고 명확하게 읽을 수 있는 Document를 적는 것도 하나의 업무이자 미래이자 올바른 방향임에 틀림없다고 생각한다.