Lorna Mitchell은 Redocly에서 테크니컬 라이터로 일하고 있습니다. 소프트웨어 개발자 경험이 있고 기술 서적을 출판한 경험이 있습니다. 이번 강연은 어떻게 보면 낯선 환경에 들어서야 하는 테크니컬 라이터를 위한 강연인데.... 너무 원칙적인 이야기하면 해서 그럼 어떻게 해야하는데라는 질문이 나올 수밖에 없네요. Q&A에서도 언급되었지만, 그건 각자 알아서 공부하라는...
DevOps의 간략한 정의
- Dev: 소스 컨트롤, 코드 개발 도구
- Ops: 빠른 피드백, 지속적인 개선
이 강연에서 배운 것을 활용하기 위한 전제 조건
- 기술 문서는 텍스트 기반으로 작성되어야 합니다(예를 들어 마크다운 같은. 텍스트 기반 콘텐츠의 장점은 서식을 설정하거나 맞춤법 검사 등 도구와 연결하는데 매우 좋습니다).
- 문서 내에 다이어그램 역시 코드 기반으로 작성되면 좋습니다.
- 문서의 프레젠테이션 영역과 콘텐츠는 분리되어야 합니다(나중에 회사가 다른 곳에 팔려나가더라도 문서를 쉽게 갱신할 수 있습니다).
- Git 같은 버전 컨트롤 도구를 사용해야 합니다(Git은 변경 사항을 검토하고 모든 변경 이력을 관리할 수 있는 최상의 무료 도구입니다).
Automate
- 개발 조직에서 이미 사용하고 있는 프로세스에 올라탈 수 있는 환경이라면 좋겠지만 그렇지 못한 환경도 있습니다. 이번 강연은 그런 분들을 위해 바닥부터 어떻게 시작하는지 가이드하려고 합니다.
- 4단계를 설명하는데(1단계부터 어떤 것을 선택하라는 거야 싶긴 하네요. 앞에서 언급한 것처럼 주변에 이런 프로세스를 다루어본 적이 없는 환경이라면 도구를 선택하는 것부터가 쉽지 않거든요) 하여간 단계는 아래와 같습니다.
(1) 어디에서다 실행할 수 있는 도구를 선택하세요(로컬 환경에서도 실행할 수 있는 도구를 이야기합니다).
(2) 로컬 환경에서 설정하고 실행해 보세요.
(3) 성공한 실행 절차를 문서화하고 설정을 저장소에 저장하세요(공동으로 작업하는 이들이 같은 설정을 사용할 수 있게 합니다).
(4) 모든 풀 리퀘스트를 자동화하세요(3단계에서 4단계는 뭔가 확 뛰어넘는 느낌이네요).
Continuous integration
- 배포 단계에서 맞춤법 검사기 같은 도구를 추가하고 이를 테스트해 보세요. 테스트를 위해서는 실패하도록 문서를 작성해야 합니다(맞춤법 검사기가 제대로 동작하는지 확인하려면 틀린 맞춤법을 사용한 문서가 필요하겠죠. 생각보다 이걸 모르고 테스트하는 경우가 많습니다).
- GitHub Action 같은 것을 사용한다면 비슷한 문서화 플랫폼을 사용하는 분들이 공유한 템플릿을 찾아볼 수 있습니다.
Automation thinking
- 배포 단계에서 오류가 발견된다면 배포를 멈추어야 하지만 심각하지 않는 수준의 실수라면 일단 배포하고 수정하는 방법을 선택할 수 있습니다.
몇 가지 도구
- 링크 검토: 내부 문서 간 링크만 검토하는 것을 권장합니다. 외부 링크까지 검토하려면 시간과 비용(아마 서버 비용을 이야기하는 것 같은데)이 많이 들어갈 수 있습니다.
- Preview builds: 스테이징 서버 환경이 있다면 좋지만 그렇지 못하다면 사전에 검토할 수 있는 콘텐츠를 만드는 것이 중요합니다(Redocly 같은 경우에는 이전 버전과 비교할 수 있는 도구도 제공한다는 뭐 그런 광고를...).
- Vale: 맞춤법, 문법 검사 도구입니다. 아마도 이걸 이야기하는 듯합니다.
https://github.com/errata-ai/vale-action, https://vale.sh/
발표자 블로그에서 비슷한 내용을 담은 콘텐츠 또는 발표 자료를 확인할 수 있습니다.
https://lornajane.net/posts/2024/checking-links-in-docs-as-code-projects
Q&A에서 회사 내에서 관리하는 콘텐츠가 모두 워드, 엑셀 시트인 경우에는 어떻게 하느냐는 질문이 있었는데, 딱히 답변을 하지 못했습니다. 점진적으로 개선하는 것이 좋겠지만 이건 개인의 노력보다는 문화적인 부분이라. 생각보다 오피스 문서를 맹신하
는 분들이 많고 버전 관리 없이 파일만 공유하는 경우도 많습니다. 오피스 문서를 버전 관리하는 것은 별 의미가 없는 일이긴 하지만 그래도 파일 이름을 변경해서 백업하고 관리하는 것보다는 편하겠죠 ㅠㅠ
어디에서 시작해야 하는지 감이 잡히지 않는다면 공부하세요!!라고 하네요(뭐 당연한 이야기입니다. 이런 도구들에 대해 무료로 진행되는 강연들을 많이 찾아볼 수 있습니다. 하지만 나의 상황에 맞게 이걸 어떻게 적용해야 하는 거지라고 생각하면 답을 찾기가 쉽지는 않습니다).
https://youtu.be/Puzl0WKsFSA?si=RqZExo7ZGlzzGC3v
Devops Your Docs
www.flickr.com
