수동으로 문서화와 점검으로 문서화

과거에 부서의 다른 사람들과 문서, 특히 상세 수준 및 요구 사항에 대해 토론했습니다. 그들의 관점에서, 문서는 X 일이 잘못되었을 때해야 할 Y 일에 대한 간단한 점검표입니다.

동의하지 않습니다. 이는 IT의 모든 문제를 간단한 복구 절차 점검 목록으로 쉽게 정리할 수 있다고 가정합니다. 상황의 복잡성을 완전히 무시하고 부서의 다른 사람들이 항상 문제에 대해 깊이 이해하지 못하기 때문에 (문서를 작성하는 이유-참조 할 것이 있습니다.) ) 문서에는 다음과 같은 기본 배경 자료가 포함되어야합니다.

• 문제의 서브 시스템의 목적
• 왜 그런 식으로 구성되어 있습니까?
• 설정 / 프로 시저가 구현 될 때 발생할 것으로 예상되는 이벤트
• 절차 실패를 일으킬 수있는 잠재적 문제

내 문서가되도록 그러나, 나는 오히려이에 outvoted있어 필요한 재 작성 말한다 형태로 될 "단계 ABC는 문제 X를 해결할 순서대로 적용". 나는 종종 한 페이지에 맞는 애가를 듣습니다. 단일 페이지 문서를 통해 문제 해결을 포함하여 이런 방식으로 Squid ACL의 구성을 누군가에게 설명하십시오. 복구 점검 목록으로 "기다리기 위해 기다리고있는"6 개의 문서 중 하나 일뿐입니다.

내가 옹호하는 방법이 실제로 선상에 있습니까? 또는 그들이 옳은가, 나는 단지 내 사업을 염두에두고 간단한 점검표를 작성해야합니까? 내 관심사는 프로 시저 체크리스트를 아무리 잘 작성하더라도 SysAdmin이 생각하는 문제를 실제로 해결하지 못한다는 것입니다. 문서의 초점이 좁기 때문에 문서의 일부가 아닌 추가 요소가 있기 때문에 문제를 해결하지 못하는 복구 절차 검사 목록을 작성하는 데 시간을 소비하고있는 경우 문서는 매뉴얼 페이지, 위키 및 웹 사이트를 다시 읽지 않기 위해 작성되었습니다. 그렇다면 왜 모션을 진행합니까? 너무 걱정이 되나요? 아니면 이것이 진짜 문제입니까?

편집하다:

현재 부서에 헬프 데스크 위치가 없습니다. 문서의 대상은 다른 관리자 나 부서장을위한 것입니다.

내 글을 쓸 때 나는 항상 두 세 세트 를 쓰는 데 집중했습니다 . 시스템 구조에 대한 자세한 정보가 포함 된 완제품 점검표, 시스템 작동 방식, 온라인으로 연결될 때 발생할 수있는 고정 지점 및 추상적 인 설계 가정 등이 포함됩니다. 그 뒤에 가능한 문제와 해결 방법 목록, 시스템 작동 방식, 시스템 작동 방식에 대한 정보 및 고유 한 상황이 발생했을 때 올바른 방향으로 사람들을 지시하는 데 유용한 기타 정보가 포함 된 더 긴 섹션이 이어집니다.

마지막 직장에서 우리는 1 급 헬프 데스크 사람들이 일을 다시 시작할 수 있도록 문서를 작성해야했습니다. 이 필수 점검표는 일반적으로 서면 3 개월 이내에 만료되었습니다. 우리는 가능할 때마다 문제 해결 가이드를 작성해야했지만, 우발성 트리가 3 개 이상의 분기를 가지면 초록없이 문서를 작성할 수 없습니다.

마지막 직장을 떠날 때 떠나기 전에 100 페이지의 '내 일을하는 방법'매뉴얼을 보았습니다. 여기에는 추상적 인 점, 디자인 철학 및 통합 지점이 있습니다. 아마도 나를 대신 할 다른 시스템 관리자를 위해 글을 쓰고 있었기 때문에 추상적 인 개념을 취하여 구체적인 행동으로 바꿀 수있는 사람을 목표로 삼았습니다.

5 년이 지났는데 이것에 대한 나의 의견은 다소 바뀌었다. 모두 수동으로 문서 및 체크리스트 등의 문서는 문서의 계층 구조와 생산되는 양을 필요로하는 매우 가치있는 장소가있다. 그러나 그들은 매우 다른 청중을 목표로합니다.

점검 목록으로 문서

이런 종류의 문서화를위한 목표 시장은 어떻게 일을 하는지를 원하는 동료들입니다. 그들은 두 가지 유형으로 제공됩니다.

• 일을하는 방법을 알고 싶어하고 15 페이지의 매뉴얼을 살펴볼 시간이없는 동료들.
• 절차는 단계적으로 복잡하지만 한 번에 한 번만 실행하면됩니다.

조바심은 첫 번째 종류의 동인입니다. 동료가 실제로 출력을 90 문자 펄 정규식을 통해 파이프 해야하는 이유 를 알고 싶지 않을 수도 있습니다 . 단지 티켓을 닫으려면해야합니다. 이유를 알고 싶은 사람들을위한 체크리스트에 "이 워크 플로가 왜 이런 모습인지에 대한 자세한 설명을 보려면이 링크를 따라 가십시오"와 같은 문구를 포함하십시오.

두 번째 요점은 자주 실행되지 않지만 함정이 포함 된 절차입니다. 체크리스트는 특정 운명이 그냥 날아 다니는 것을 피하기위한 맵 역할을합니다. 점검 목록이 문서 저장소에 보관되어 있으면 이전 관리자가 HOWTO를 보낸 시간 동안 전자 메일을 검색하지 않아도됩니다.

제 생각에는 좋은 점검표 문서에는 가능한 실패 지점에 대한 섹션과 이러한 실패에 대한 응답도 포함됩니다. 이렇게하면 문서가 다소 커지고 동료의 TL; DR 응답이 트리거 될 수 있으므로 실패 모드와 해당 응답을 페이지 자체가 아닌 체크리스트의 링크로 만드는 것이 무의미한 체크리스트를 만듭니다. 하이퍼 텍스트를 받아들입니다.

수동 문서

이러한 종류의 문서를위한 목표 시장은 시스템 작동 방식에 대해 더 많이 배우려는 사람들입니다. 작업 방법 스타일 문서는이 문서에서 파생 될 수 있지만, 워크 플로우에서 내린 결정을 뒷받침하는 체크리스트 스타일 문서의 보충 자료로 더 일반적입니다.

이것은 다음과 같은 질긴 조각을 포함하는 문서입니다.

• 왜 이런 식으로 구성되어 있는지 설명하십시오.
  • 이 섹션에는 전체 구매 및 설치 방식을 둘러싼 정치와 같은 비 기술적 문제가 포함될 수 있습니다.
• 일반적인 실패 모드와 그에 대한 설명.
• 서면 및 사실상의 서비스 수준 계약에 대해 설명합니다.
  • 사실상 : "결승 주간에 실패하면 모든 문제가 발생합니다. 여름 방학 동안 다시 잠을 자고 아침에 처리하십시오."
• 업그레이드 및 리팩토링 목표 설정
  • 나중에 정치가 다를 수 있습니다. 왜 처음에 소개 한 나쁜 생각들을 고쳐 보지 않겠습니까?

이는 전체 시스템에 대한 포괄적 인 이해를 얻는 데 매우 유용합니다. 간단한 인간-자동화 작업을 실행하기 위해 포괄적 인 이해가 필요하지 않습니다. 왜 어떤 일이 왜 그랬는지 알아 내고 다시는 그렇게하지 않아야 할 아이디어가 있어야합니다.

점검 목록이어야하는 재해 복구 설명서도 언급했습니다.

이해합니다, 당신은 내 동정심을 가지고 있습니다.

예, DR 문서는 가능한 체크리스트와 유사해야합니다.
예, DR 문서는 여러 가지 방법으로 인해 점검 목록에 가장 저항력이 있습니다.

DR 점검 목록이 다음과 같은 경우 :

1. 더스틴이나 카렌에게 전화하십시오.
2. 문제를 설명하십시오.
3. 다시 서.

당신은 문제가있다. 이것은 체크리스트가 아닙니다. 즉,이 시스템의 복구가 너무 복잡하여 건축가가 알아내는 것이 허용됩니다. 때때로 그것은 당신이 할 수있는 전부이지만, 가능하다면 그것을 피하려고 노력하십시오.

DR 문서에는 몇 가지 다른 것들에 대한 절차 점검표가 포함됩니다.

• 무엇이 잘못되었는지 파악하기위한 심사 절차를 통해 식별하는 데 도움이됩니다.
• 특정 장애 사례에 대한 복구 절차. 어느 지원 ...
• 복구 중 인적 오류를 최소화하기 위해 미리 작성된 복구 스크립트
• 실패 사례, 발생 원인 및 의미에 대한 수동 스타일 문서

심사 절차는 때때로 일부 시스템에 대해 만들 수있는 모든 DR 설명서입니다. 그러나 오전 4시 콜 아웃은 이해하기 쉽고 복구를 담당하는 수석 엔지니어는 실제 문제를 더 빨리 해결할 수 있습니다.

일부 실패 사례에는 간단한 복구 절차가 있습니다. 문서화하십시오. 그것들을 문서화하는 동안 명령 목록이 특정 순서로 입력되는 경우를 발견 할 수 있는데, 이는 스크립팅의 훌륭한 사용 사례입니다. 96 포인트 복구 절차를 20 포인트로 전환 할 수 있습니다. 복구 절차 작업을 작업별로 매핑 할 때까지 무언가를 스크립팅 할 수 있는지 알 수 없습니다.

고장 사례에 대한 수동 스타일 문서는 복구 절차가 없거나 복구 절차가 실패한 경우에 사용되는 마지막 도랑 백스톱입니다. 그것은 그 문제를 겪고있는 다른 사람과 그 문제를 해결하기 위해 무엇을했는지 알아내는 데 필요한 구글 힌트를 제공합니다.

실제로, 우리는 시험용 문서 를 사용하지 않습니다.

우리는 Documentation As-a-Manual 과 함께 제공되는 문서를 작성했습니다 . 우리는 점검 목록을 마련했지만 성장할 때 오류가 발생하기 쉽고 시스템 전체에서 실제로 실패한 것으로 나타났습니다.

그러나 우리는 일종의 "Check-as-a-Checklist"를 설치했습니다. 즉, 위에서 언급했듯이 서비스를 광범위하게 모니터링합니다. 다음과 같은 말이 있습니다.

모니터링하지 않으면 관리하지 않는 것입니다

그것은 완전히 사실이지만 다른 하나는 다음과 같아야합니다.

모니터링하지 않으면 문서화하지 않은 것입니다

서비스를 마이그레이션해야 할 때마다 "서비스 그룹", "호스트 그룹"을 적용합니다 (어휘에서 짐작할 수 있듯이 Nagios를 사용함). 모든 서비스에.

테스트는 수작업으로 작성된 체크리스트보다 훨씬 나은 체크리스트를 제공합니다. 실제로 모니터링되지 않은 오류가 발생하자마자 테스트는 Nagios에 추가되어 2 가지 무료로 제공됩니다.

• 우리는 그것이 실패 할 때를 안다
• 점검 목록의 다른 지점

"실제"문서는 특정 서비스 나 테스트의 가능성과 끝을 언급하는 위키에 보관됩니다. 누락 된 사람들은 마이그레이션을 수행하거나 작업을 수행 해야하는 즉시 추가 할 것입니다. 지금까지 그 접근 방식은 매우 효과적이었습니다.

또한 잘못된 문서는 정말 빨리 다림질됩니다. 무언가가 실패 할 때마다 사람들이 문서를 찾기 시작하고 거기에있는 HowTos의 문제를 해결하려고 시도합니다.

점검표를 따르고 적용 후 녹색 체크 박스를 표시하는 테스트를 설치하지 않아 발생할 수있는 오류를 생각하십시오. 문서와 모니터링을 분리 할 수 ​​없다고 생각합니다.

문서의 대상 독자에 따라 다릅니다.

헬프 데스크 (수준 1) 유형의 경우 점검 목록이 올바른 방법입니다. 물론 이것은 당신이 묘사하는 더 깊은 지식으로 더 높은 수준의 지원이 있다고 가정합니다.

설명서가 시스템 그룹 용인 경우에는 항상 추가 설명서 측면에서 오류를 범합니다. 누군가 (자신)가 필요한 배경 정보로 더 광범위한 문서를 작성하려는 경우, 적절한 문서를 확보하기가 어렵습니다.

개인적으로 나는 가능한 한 간단하게 문서를 작성하려고 노력합니다. 다음을 포함하는 경향이 있습니다.

• [X]가해야 할 일 (요구 사항).
• [X]가 어떻게 고수준 (디자인)으로 구성되어 있는지.
• 내가 수행 한 방식으로 [X]를 구현 한 이유 (구현 고려 사항).
• [X]의 구현이 표준이 아닌 방법 (해결 방법).
• [X]의 일반적인 문제와 해결 방법 (문제).

따라서 필자의 일반적인 문제 섹션은 발생한 문제에 대한 간략한 설명 일뿐 아니라 문제를 해결하는 방법에 대한 연습이 될 것입니다.

나는 일반적으로 문제의 시스템 독자로부터 약간의 지식을 얻는다 (특히 비전이 아닌 한). 기술 문서 수준 1 또는 관리를 대부분 읽을 수있는 시간이 없지만 cluey 수준 3은 괜찮습니다.

나는 그것이 주제에 분명히 달려 있다고 생각합니다. 모든 것이 간단한 점검 목록으로 축소 될 수있는 것은 아니며 모든 것이 상세한 사용자 설명서가 필요한 것은 아닙니다.

내부 문서에 대해 이야기하고있는 것처럼 들릴 것입니다. 제 경험상 너무 많은 선택 사항이 있기 때문에 단계 목록을 제공 할 수는 없습니다. 사용자 계정을 만들더라도 환경에 따라 몇 가지 옵션이 있으므로 "새 계정"문서에는 기본 단계가 순서대로 나열되어 있지만 각 단계마다 변형 내용에 대한 설명이 있습니다.

다른 한편으로, 우리는 "사무실에서 패치하는 방법"에 대한 많은 문서를 작성하지는 못했지만 스케치 문서도 점검표가 아니 었습니다. 당신이 것을 가지고 연결을 나열 스프레드 시트를 업데이트하고, 그것에 대해이었다.

그래서, 나는 이것을 작성 했으므로 완전히 동의합니다. 단계별 체크리스트는 많은 프로세스를 위해 그것을 잘라 내지 않을 것입니다.

나는 문서에 전혀 관심이없는 전임자가 있기 때문에 부분적으로 철저한 문서화를 위해 이것에 대해 당신에게 강력히 동의합니다. 관련 게시물에서 언급했듯이, 글을 쓰면 다른 사람에게도 좋을뿐만 아니라 자신의 환경을보다 완전히 이해하고 자신의 마음으로 공고히 할 수 있습니다 . 그것은 그 자체의 끝입니다.

제쳐두고, 나는 많은 푸시 백이 엉터리 / 존재하지 않는 문서화 = 직업 안전이라는 이상한 신념에서 비롯된 것을 발견했다. 그런 생각은 부정직하고 그늘진 것 같습니다.

현상 유지에 대한 여러분의 의견.

나는 상당히 많은 문서를 작성하고 심지어 문서 우선 순위 점검 목록을 가지고 있습니다 :-), 그러나 일반적인 지식으로 간주 될 수있는 것들을 문서화하지 않을 것입니다 (즉, 문제에 대한 합리적인 좋은 설명은 Google의 첫 페이지 내에 답변을줍니다).

여기에 관심이있는 사람은 내 문서 prio 점검표입니다 (저에게 도움이 될 수 있습니다. 의견과 제안은 높이 평가됩니다).

1. 업무 / 지식을 현명하게 수행 한 모든 내용을 기록하는 개인 로그 / 일지를 작성하십시오.
2. 서비스, ​​서비스의 위치, 서비스 및 대상은 무엇입니까 (SLA 계약은 무엇입니까? 계약을 작성해야합니까?)
3. 서버, 서버의 위치, 연령 및시기
4. 위와 같지만 네트워크 장비, UPS 등
5. 위와 같지만 모든 사용자 컴퓨터
6. 물리적 네트워크의 레이아웃 (어느 케이블이 어디에서, 얼마나 오래, 측정 품질이 어떤지)
7. 서버용 소프트웨어 및 라이센스의 구성 개요
8. 사용자 컴퓨터의 소프트웨어 및 라이센스 구성 개요
9. 스위치, 라우터 및 기타 전용 하드웨어의 구성 개요
10. 내 서비스가 직접 의존하는 모든 외부 당사자의 계약 및 SLA (ISP, 도메인 등)
11. 위의 모든 것을 넣을 수 있도록 위키가 통합 된 티켓 시스템을 설정하십시오.
12. 모든 사건에 대해 티켓을 만드십시오 (자신만을 위해 사용하더라도).
13. 일요일에 티켓을 수집하여 문제점 유형별로 그룹화하는 스크립트를 작성하십시오.
14. 월요일에 가장 자주 발생하는 문제에 대한 자동 솔루션 또는 최종 사용자 하우투 문서 작성
15. 시간이 허락하면 다음을 수행하십시오.
16. 더 이상 할 일이 없다면, 새로운 직업을 찾아 당신을 대신하는 사람에게 로그를주십시오 ;-)

완전한 문서화 를하지 않는 한 점검표는 괜찮습니다 . 내가 쓴 마지막 몇 문서는 두 부분으로 나뉩니다. XYZ for Users. 사용 방법에 대한 예쁜 스크린 샷이 포함되어 있습니다. 시스템 관리자를위한 XYZ (설정 방법, 존재 이유에 대한 비즈니스 요구 사항 포함), 피해야 할 함정 및 문제 해결 섹션이 포함 된 시스템 관리자 용 XYZ. 문제 해결은 체크리스트를 찾을 것으로 예상되는 곳입니다. 기술 지원을위한 XYZ로 체크리스트를 작성하는 것이 도움이 될 수 있습니다.

이제 체크리스트에만 초점을 맞추고있는 줄 사이를 읽으면서 "큰 그림"사고와 장기 계획이 부족하다는 것을 알 수 있습니다. 기술 지원을 한 사람 만 있습니다. 또는 주니어 관리자가 막 시작했습니다. 또는 일에 너무 푹 빠져서 생각할 시간이 없다. 또는 그것에 대해 생각하도록 강요된 적이 없습니다. 아니면 그냥 평범하지 않습니다. 이 중 어느 것이 귀하의 경우에 적용되는지 모르겠습니다.

나는 문서에 꽤 크다. 내가 일하는 회사는 이제 문서가 중요하다고 생각하지만 회사의 일부 사람들은 문서를 작성할 시간이 없다고 생각합니다. 이것은 원래 사람 외에 다른 사람에게 인생을 어렵게 만들 수 있습니다.

특정 사항에 대해서는 단계별 지침을 작성했습니다. 원한다면 이것을 체크리스트라고 부를 수 있지만 실제로 물리적으로 체크되지는 않습니다. 나는 문서 스타일을 "유치원 단계"라고 부릅니다. 그것은 Windows 2000 시험 중 하나에 대한 MCSE 연습장을 본 후에 패턴 화되어 있습니다. 단계는 매우 상세하지만 굵은 체 / 이탈리아어 / 서체를 사용하면 쉽게 광택을 내고 중요한 부분을 선택할 수 있으므로 단계를 학습 한 후 모든 것을 읽을 필요가 없습니다.

단계별 지침에는 적합하지 않은 항목이 있으므로 최대한 많은 구성 데이터를 제공하려고합니다. 기술적으로 기울어 진 일부 사람은 길을 계속 유지하면서 자신이 무엇을 반대하는지에 대해 더 잘 알 수 있으며 무언가 잘못되면 인생이 조금 더 쉬워지기를 바랍니다.