설명서 시작하기

우리는 내 직장에서 문서를 작성하지 않았습니다. 나는 완전히 새로운 것을 시작하고 몇 가지 지침을 시작하도록 요청합니다.

몇 가지 질문이 있습니다.

• sysadmin이 작성하고 유지 관리해야하는 필수 문서는 무엇입니까? 그리고 이것이 왜 그렇게 중요한가?

• 문서를 시스템과 동기화 된 상태로 유지하는 방법은 무엇입니까? 정보 중복을 어떻게 최소화합니까?

• 권장 가이드, 모범 사례, 안티 패턴?

2003 년부터 사내 위키의 모든 것을 문서화 하고 있습니다.

서버

• 하드웨어 사양
• 보증 정보
• 네트워크 정보
• 물론 설치된 소프트웨어 및 구성

워크 플로우

예 : 사용자를 추가 또는 삭제하고 모든 관련 서비스에 액세스하는 방법

중요한 링크

• 모든 웹 인터페이스에 연결
• 모니터링 URL 링크 (nagios, munin, apc-monitoring ...)
• 위키 링크 (인쇄본)!

긴급 지침

인트라넷 서버 / 인터넷 / 웹 서버 / 등이 다운 된 경우 수행 할 작업

중대한:

PDF로 쉽게 내보낼 수있는 위키 엔진을 선택하십시오!
휴가 중이라면 위키를 실행하는 서버가 다운되어 문서가 오프라인 상태이므로 아무도해야 할 일을 모른다면 유용하지 않습니다.

twiki, docuwiki 또는 mediawiki를 살펴보십시오.

BTW :

미디어 위키에 직접 쓸 수 있는 OpenOffice.org 플러그인 이있어 매우 편리합니다.

편집하다:

정보를 적어 두는 것도 좋습니다 /home/adminuser/maintenance. 여러 관리자가 서버에서 작업하는 경우이 작업은 빠르게 수행되며 매우 유용합니다. 예 :

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

모든 사람이 문서를 원하고 필요로하지만, 아무도 문서를 읽고 공부할 시간이 없다는 것을 인식해야합니다.

따라서 연구해야 할 문서를 작성하지 마십시오. 대신 필요한 정보를 필요할 때 신속하게 찾을 수있는 방식으로 문서를 구성하십시오. 시스템이 다운되고 CTO가 작동하는 동안에도 마찬가지입니다. 목을 호흡.

이것을 염두에두고 몇 가지 제안 ...

• 큰 텍스트 블록을 피하십시오
• 글 머리 기호 목록은 친구입니다
• 명확한 다이어그램은 황금입니다
• 반복하는 것이 좋습니다 (1)
• 손쉬운 업데이트 및 확장

(1) 진실의 한 근원을 만들어 사람들이 그것을 쫓아 내도록 강요 하지 마십시오 . 아이디어가 중요할수록 반복해야합니다.

필수 문서 :

• 서버 설명서-사양 / 디스크 레이아웃 / 설치된 소프트웨어 / 기타 사항
• 일반적인 절차- '사소하지 않은'수행 된 모든 절차, 특히 이전에 수행되지 않은 절차 인 경우 절차를 문서화해야합니다.

문서를 동기화 상태로 유지하는 것은 '실수를 볼 때 수정'일이 될 수 있습니다. 이와 함께 문서가 구식이 될 수 있고 구식이 될 것이라는 인식과이를 고려하지 않고 맹목적으로 따라서는 안된다는 인식이 필요합니다. 비판적 사고를 대체하는 일련의 규칙이 아니라 관리자가 작업을 지원할 수 있도록 문서화되어 있습니다.

복제 최소화-문서를 서로 연결할 수있는 위키와 같은 정보를 사용하면 정보를 반복하는 대신 이에 도움이 될 수 있습니다. 문제는 문서를 작성하는 사람이 복제하려는 정보가 이미 존재한다는 것을 알아야한다는 것입니다. 이것은 일반적으로 좋은 조직의 문제입니다.

템플릿을 만드는 것이 큰 도움이된다는 것을 알게되었습니다. 내 경우에는 Word 템플릿이지만 스위트를 사용하십시오. 원하는대로 목차 필드와 섹션으로 완성 된 스켈레톤 파일을 만듭니다. 두 번 사용하고 미세 조정을 조정하면 새 문서를 훨씬 빠르게 만들 수 있습니다. 형식의 일관성은 문서 작성 및 나중에 사용하는 데 큰 도움이됩니다. 설명서는 논리적 위치와 논리적 디렉토리 구조에 저장해야합니다.

나는 개인적으로 그것이 불필요하게 유지를 어렵게하고 시간을 소비한다는 단순한 사실에 대한 반복에 반대합니다. 문서 또는 문서의 일부를 복제하지 않고 적절한 경우 다른 문서에 대한 참조를 작성하십시오. 뭔가, 더 많은 다음 번 또는 두 개 이상의 장소에서 관련 문서를 변경하지 않아도해야 변경하는 경우 그렇지 않으면 것이다 아무도 할 수없는 충돌 문서의 컬렉션을 보유하고 있습니다.

설명서를 작성하는 동안 설명서의 내용을 명심하십시오. 나중에 누군가 그것을 사용해야 할 것입니다. 사전 지식없이 업무를 수행 할 수 있습니까?

귀하의 질문에 대한 직접적인 대답은 아니지만 올바른 방향의 포인터 :

내가 발견 시스템 및 네트워크 관리의 연습 이 같은 문서로 "가장 좋은 방법"문제에 대해 있기 때문에 매우 가치있는 것으로 Limoncelli와 (은 sysadmin 성경 일명) 호건. 아직 모르는 경우 기회가있을 때마다 조사해야합니다.

나에게 가장 중요한 고려 사항은 사용하기 쉽다는 것입니다. 오케스트레이션하기 어려운 경우 사람들은이를 피할 것입니다. 다음과 같은 이유로 Trac 의 위키를 문서의 매체로 선택합니다 .

• 중심부에 위치한.

  하나의 문서에 대해 둘 이상의 활성 사본이 혼동 될 수 있습니다. 모든 사람을 기고자와 청중 모두 같은 장소로 안내 할 수 있다면 프로세스를 단순화 할 수 있습니다.

• 간단한 편집 및 서식

  예쁜 Word 템플릿에 많은 시간을 소비하고 마지막 저자의 스타일을 준수합니다. 이것으로 사람들을 혼란스럽게 만들지 않으면 이동 중에 편집하기가 더 쉽고 기고자들이 더 기울어집니다. TracLink로 원하는만큼 항목을 분리하십시오.

• 감사 기록.

  누가 언제, 왜 어떤 변화를했는지 아는 것이 중요합니다. 변경 요청 티켓과 구성 커밋 로그에 묶을 수 있다면 더 좋습니다. SVN commit hooks는 이것에 좋습니다.