ADR 도입기 - (2) Doc as a code의 Deploy, user guide와 SRS 관리 방법 검토

우리 부서에 맞는 ADR (Architecture Decision Record) 템플릿 작성과 ADR 시스템 도입

 

ADR 도입기 (1) - ADR 도입에 대한 팀원들의 의견과 피드백

이전 포스트에 이어서 3번째 글입니다.

1. Doc as a code 의 Deploy

ADR, Architecture 문서를 도입 한 이후에 문제가 하나 있었습니다.

1. 첫 번째로는 깃허브에 직접 ADR 파일을 올리고 링크를 눌러서 켜야하는데, 반응성이 좋지는 못했습니다. (문서를 누르고 켜는데 2초정도 소모 - 리더님 제보)

2. 두 번째로는 어디에 어떤 문서가 있는지에 대해서 파악이 힘들었습니다.

이 두 가지 문제점을 해결하기 위해서 Doc as a code를 도입을 하게 되었는데요.

 

기존의 ADR,Architecture 문서의 결정 사항은 그대로 둔 채로 doc as a code를 지원할 수 있는 툴을 찾고있었습니다.

아래 요구사항정도가 있었는데요.

 

1. 여러 Repository를 한번에 출력 할 수 있어야함.

2. 버전 별로 출력할 수 있는 기능이 필요함.

3. Github Pages 를 사용할 수 있으면 좋음.

- 사내 깃헙의 버전이 높아 Github Pages 및 Action을 지원하며

- Github Pages의 경우 도메인에 대해서 자동 생성을 해주기 때문에 사내 도메인을 따로 신청하지 않아도 되고

- Github Action을 통해서 자동 Deploy까지 할 수 있기 때문입니다.

4. markdown, mermaid, code highlight를 지원해야함 (ADR, Architecture)

 

처음에는 여러개의 후보를 찾아보다가 MKDocs, Docsify등을 찾았습니다.

그래서 위의 대부분의 기능을 플러그인으로 지원하는 Docsify로 가도 되겠다 생각했습니다.

실제로 아래의 example repository에서 테스트도 끝난 상황이었거든요.

GitHub - ray5273/docsify-template: docsify-template

다만, 일부 플러그인들이 중국어 설명 으로 되어있거나 충분한 Star수가 없고 문서화가 아주 잘되어있지는 않아서 불편한 점은 있었습니다. 그만큼 직접 개발해야하는 기능들이 생기기 때문이죠.

 

Docsify를 거의 확정짓고 잡다한 기능이 가능함을 확정을 지으려다가 갑자기 docusaurus가 보였습니다.

Docsify 검색하면서 Docsify의 깃헙 issue에 언급되어있기도 했는데 사실 무료인지는 모르고 있다가 우연히 Documentation 사이트를 들어갔는데 무료라서 검토는 해보려고합니다.

 

페이스북에서 만든 툴이라 더 공식적인 자료도 많고 Support도 많아보였습니다.

그리고 필요한 대부분의 기능을 plugin의 형태가 아닌 직접 지원하는것도 그렇고 

Star 수도 많고, 영어권이기까지해서 아마도 조금 더 쓰기 좋은 형태가 아닌가 싶습니다.

 

Build optimized websites quickly, focus on your content | Docusaurus

 

사용법은 조금 더 어려울 수는 있지만 검토를 다른 포스트를 통해서 진행하려고합니다.

 

 

2. 다른 문서들(Userguide, SRS) 도 코드로 관리하고 싶다.

ADR,Architecture 외에도 다른 문서들을 코드로 관리하고 싶다는 의견도 있었습니다.

그래서 이를 검토하기 해보려고했습니다.

현재 필요한 내용은 Userguide, SRS 문서들에 해당합니다.

이런 니즈들을 보면 더 있는지는 모르겠지만 코드의 버전을 따라가는 모든 문서들이 코드로 들어오고 싶을 수 있겠다는 생각이 들긴했습니다.

 

우선은 지금 검토 중인 2개 문서의 요구사항을 먼저 검토해보도록 하겠습니다.

 

 

UserGuide 문서의 요구사항

대상 : 고객사와 소프트웨어를 쓰는 평가팀 (한국인 + 해외 연구소)

기존에는 워드 파일로 Userguide를 작성하고 고객사/평가팀에 전달한 것으로 생각됩니다.

실제 내용을 확인해 봤을때는 아래와 같은 내용들이 포함되었습니다.

1. 설명을 위한 영어 텍스트 글

2. 코드라인 

3. 커맨드 실행 결과를 붙여넣은 캡처 사진

정도였습니다.

 

파일 형식은 Microsoft Word 이긴 했는데 PDF로 바꿔도 문제는 없는 수준으로 보이긴 합니다.

word를 쓴 이유는 tech 문서 작성하시던 분들이 대부분 word에 적합한점

아마도 기존의 관련 템플릿이 워드로 존재했었기에 그냥 쓰지않았나 생각이 들었습니다. 

그리고 그 템플릿에는 회사의 워터마크가 존재하기도 했구요.

 

약간 걱정인 부분은 UserGuide의 경우에는 좀 더 공식적인 포맷에 가까워야 좋을것 같은데 그것을 Template 화 할 수 있을지가 걱정이네요.

템플릿 부분은 Docusaurus의 export 기능을 확인해 보고 다시 이 글로 와서 추가해 볼 예정입니다.

템플릿이 여러개 필요할지도 모르겠다는 생각은 듭니다.

(여기에 Template 추가 예정)

 

SRS 문서의 요구사항

SRS(Software Requirement Specification)에 대한 요구사항을 정리해봤습니다.

 

대상 : 소프트웨어를 쓰는 평가팀 (한국인 + 해외 연구소)

기존에는 컨플루언스에서 관리를 했습니다.

형식은 정해져 있었고 그 형식은 대부분 표 안에 텍스트가 구성되어있는 수준이었습니다.

따라서, 이런 문서는 어디에서 보관하든 내용은 비슷해서 상관은 없어보였습니다.

다만, 컨플루언스에는 문서가 너무 많아 검색 능력이 낮아져서 검색하기 힘든 문제가 있었습니다.

 

그래서 SRS의 요구사항을 아래와 같이 정할 수 있겠습니다

1. 컨플루언스에 파일을 보관하고 싶지 않다. (검색 능력을 위해)

2. 컨플루언스에서는 버전별 SRS 관리가 힘든데, 버전별로 관리하고 싶다. (우리의 소프트웨어와 생명주기가 비슷했으면 좋겠다.)

3. 구독 대상이 쉽게 볼 수 있으면 좋겠다.

4. 기능 전체에 대한 SRS가 한번에 모여있으면 좋겠다.

 

이정도가 될 수 있겠네요.

이 요구사항들은 기존 ADR,Architecture와 비슷한 요구사항이라서 크게 들여오는건 문제가 되지 않을것같습니다.

다만, 문서 배치 위치와 문서 생산 주기 조금 다를 수 있겠는데요.

 

ADR,Architecture 문서는 각 기능을 개발하고있는 repository에 보관하고 그 버전을 따라가게 해두고 있습니다. 

어차피 그 기능들을 개발하는 개발자들이 보려고 하는 문서이기 때문이죠.

그리고 코드가 개발되면 그 시기에 바로바로 문서를 작성해서 넣죠.

 

다만, SRS의 경우는 비슷하게 할수도 있지만 조금 다릅니다.

개발 될때마다 넣는것도 좋지만 결국은 평가 위한 용도가 큽니다.

따라서, Release 마다 한번씩 확인할 예정이니 그 주기에 맞게 작성되어야합니다.

또한, ADR, Architecture와 다르게 한곳에 모여있으면 좋을것 같습니다.

 

다행히 우리의 경우에는 multi-repository 정책을 가져가고 있고

위의 목적에 맞는 repository가 존재해서 그곳에다 배치를 하면 좋을것같습니다.

 

SRS 템플릿은 사실 이미 있는게 있어서 그걸 markdown으로 바꾸기만 하면 될것같습니다.