개요

이전에 업무에서 설계서를 작성할 때 실시한 개선 활동을 정리합니다.
그 현장에서는 설계서를 스프레드 시트로 작성하는 악습이 있었기 때문에,
설계서를 Markdown에서 작성하도록 변경하여 git으로 관리할 수 있도록 했습니다.
또, 그 현장의 사내용 gitlab에서는 plantuml을 화상으로서 표시하는 기능이 제공되지 않았기 때문에,
jenkins를 사용하여 plantuml을 svg로 변환하고 Markdown과 함께 다른 서버로 전송하고,
docsify라는 도구에서 html로 참조했습니다.

전체 개요도는 다음과 같습니다.

설명

①git에 push

로컬 환경에서 편집한 Markdown 파일을 git 원격 리포지토리에 push합니다.

②push에 hook

① push 이벤트에 hook시켜 jenkins의 job을 기동시킵니다.
webhook은 gitlab의 각 리포지토리의 설정 화면에서 설정할 수 있습니다.
htps : // / cs. 기 t b. 코 m/예/우세 r/p 로지ぇct/이니 g라치온 s/우ぇb 호오 ks. HTML

③md·pu 파일 취득

jenkins의 job 내에서 git 저장소에서 Markdown 파일과,
그림 작성용 pu(plantuml) 파일을 체크아웃합니다.

④pu→svg 변환

pu 파일을 이미지로 참조하기 위해 svg 파일로 변환합니다.
jenkins의 slave 서버에 plantuml.jar를 배치하고 확장자가 pu 인 파일에 대해 변환 처리를 수행합니다.
ht tp // p 펑츠 ml. 코 m/그럼/

⑤docsify에 deploy

docsify가 실행중인 서버에 Markdown 및 svg 파일을 배포합니다.
파일의 deploy는 jenkins의 ssh 플러그인을 job 내에서 이용합니다.
htps : // 우우키. 지킨킨 s. 이오 / ぢ sp ぁ y / 지 킨 킨 S / ㅇ s + ぅ 긴

docsify는 md 파일을 쉽게 HTML로 참조 할 수있는 도구입니다.
htps : // 두 csy fy. js. rg/#/

⑥참조

검토자는 docsify에 웹 사이트로 게시된 설계 문서를 참조합니다.

⑦ 피드백

편집자는 리뷰어로부터 지적 사항을 피드백으로 받아,
설계서를 수정합니다.

피드백 루프

⑦의 피드백을 얻은 후에 설계서를 수정하고, git에 push하는 것으로 ①~⑦의 순서를 루프시켜,
피드백 루프를 사용하여 설계서를 개선하겠습니다.

궁리한 점

pu 파일의 저장 폴더 구성

docsify는 plantuml을 이미지로 인식 할 수 없기 때문에,
프로젝트의 폴더 구성은 다음과 같습니다.

ページ名(フォルダ)
 └ ページ名.assets(フォルダ)
   └ ignore(フォルダ)
     └ .pu(ファイル)

페이지명
jenkins의 job에서 처리하면 ignore 폴더의 pu 파일을 svg 파일로 변환합니다.
변환 된 svg 파일은 페이지 이름 .assets 폴더 바로 아래에 배치하고,
ignore 폴더는 폴더별로 삭제합니다.

jenkins의 job의 처리 후에는 다음과 같은 폴더 구성이 됩니다.

ページ名(フォルダ)
 └ ページ名.assets(フォルダ)
   └ .svg(ファイル)

이렇게 하면 deploy 시에 불필요한 pu 파일을 삭제하고 svg 파일만이 남도록 했습니다.
Markdown 파일에서 위의 폴더 구성 시 svg 파일을 참조합니다.

이 연구에 대해서는 gitlab의 plantuml 참조 기능을 사용할 수 있다면 신경 쓸 필요가 없으므로,
그렇게 중요하지 않습니다.

마지막으로

이번에는 설계서를 Markdown으로 쓰고 plantuml로 그려 html로 공개하는 방법의 한 예를 소개했습니다.
개요에서도 언급했지만, 개인적으로는 설계서를 엑셀이나 스프레드 시트로 작성하는 것은,
"버전 관리"나 "다른 사람이 만든 그림 편집하기 어려움"에서 생각하면 넌센스라고 생각합니다.

인프라 구성의 자동화로서 "infrastructure as code"라는 단어가 있지만,
설계서에 대해서도 마찬가지로 "as code"로서 git 관리하고, 수정이나 참조하기 쉬운 방식을 모색해 가는 풍조가
퍼지면 좋다고 생각합니다.