개인적인 정리
Shane Diven는 2018년부터 Alastair Dallas는 2019년부터 Splunk에서 테크니컬 라이터로 일하고 있습니다. Splunk는 2003년 설립되어 7500명 정도가 일하고 있는데 사용자의 플랫폼을 24시간 모니터링하는 서비스를 제공하는데 문제가 생겼을 때 내부 엔지니어는 Runbook을 참조해 대응하게 됩니다.
그래서 오늘의 주제는 "Runbook"입니다. 한국어로는 적당한 번역이 없는데 IT용어대사전에서는 "실행서"라고 표현하고 있네요. 프로세스 자동화에서는 Runbook을 작업 시나리오의 의미로 사용하고 있는데 이번 세션에서는 실제 작업자가 수행해야 하는 작업 가이드라고 이해하면 될 듯합니다.
이번 세션은 이런 테크니컬 라이터를 위한 내용으로 구성했다고 합니다.
As a writer, I want to understand the internal documentation used in high-takes situations to see if the strategies might be relevant to my users.
Runbook은 특정 작업이 어떤 식으로 동작하는지 자세한 절차를 설명하는 문서입니다.
순서에 따라 상황을 체크하고 문제가 없으면 다음 항목의 Runbook을 체크합니다.
특정 항목에 대한 Runbook은 아래와 같은 구성입니다.
- 사전 체크: 문제가 발생한 환경에 대한 확인
- 해결책: 문제 해결을 위한 절차 (특정 구성 항목값 설정 등)
Runbook에는 개념, 이론적인 설명은 배제하고 실행할 수 있는 예제나 참고사항에 집중합니다.
특히 스크린샷은 영어권 문서에서는 잘 사용하지 않는데 Runbook에서는 작업자가 정확한 화면 위치를 확인하기 위해 스크린샷이 유용한 도구로 사용되고 있습니다.
Runbook을 만드는 목적은 작업 프로세스를 표준화하는 것입니다. 표준화가 되어 있지 않다면 이를 문서화할 수도 없겠죠.
제품 문서와 Runbook은 뭐가 다를까요?
가장 큰 차이는 긴급성입니다. Runbook은 뭔가 사고가 발생하고 이를 해결하기 위한 절차를 확인하기 위한 문서이죠.
때문에 일반 제품 문서보다 task 중심적인 내용이 강조됩니다.
task 중심적이라 제목이 중요하다고 합니다.
(뭐 이건 일반 기술 문서도 마찬가지입니다).
문서 내 중요한 체크 사항은 스크롤하지 않고 바로 확인할 수 있도록 구성되어야 하고 절차가 복잡한 경우 다이어그램을 효율적으로 활용한다고 합니다(Splunk에서는 Lucidchart를 사용하고 있네요).
https://www.lucidchart.com/
비슷한 프로세스지만 버전이나 환경에 따라 조금씩 프로세스가 달라지는 경우가 있습니다.
이런 경우 가급적 중복된 문서는 만들지 않고 하나의 문서 내에서 탭이나 링크 등을 사용해 하나의 태스크에 대해서는 하나의 문서에서 다룰 수 있도록 구성합니다.
피드백의 중요성
Runbook은 현장에서 항상 사용되는 것이기 때문에 모든 문서가 최신 상태를 유지해야 합니다.
엔지니어가 문제를 발견하면 이를 피드백하고 개선할 수 있게 해야 합니다.
* Runbook과 Troubleshoot와 비슷하긴 한데...
Troubleshoot는 사용자 대상으로 일시적인 문제를 해소하거나 인지하는 것이라면 Runbook은 시스템에 영향을 미치지 않으면서 문제를 해결하기 위한 절차라서~ 좀 더 큰 범주라고 할 수 있을 듯 합니다.
위키피디아: An effective runbook allows other operators, with prerequisite expertise, to effectively manage and troubleshoot a system.
developerexperience.io: Runbook is a set of instructions on how to run a computer system. Or how to troubleshoot the system.
Q&A
Runbook은 소프트웨어 분야에서만 사용하는 건가요?
그건 아님
(하지만 위키피디아 등에 정의된 내용을 보면 시스템, 네트워크 관리자가 수행하는 작업 절차 모음이라고 설명하고 있음)
영상
현장 스케치
Alastair Dallas and Shane Diven - Lessons Learned from Cloud Ops: Writing Docs for High-Stakes Situations
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2645 photos to Flickr.
www.flickr.com
