저는 다양한 역할을 맡은 수많은 기계로 구성된 새로운 연구실 환경을 설정하고 관리하는 임무를 맡았습니다. VM 호스트, 여러 웹 서버, 여러 데이터베이스 서버 등이 있습니다.
이 랩 환경의 일부로 문서화해야 하는 매우 구체적인 요구 사항과 프로세스가 있습니다. 예를 들어 자동 Windows 업데이트를 설정하고 싶지 않으며 여러 당사자에게 설명하기 위해 캡처하고 싶은 생각이 많이 있습니다( 임원, 관리자, 개발자, IT 관리자, QA 담당자).
그래서 저는 설정을 하면서 일종의 공식적인 문서에 이러한 대화를 담아내고 싶습니다. 저는 Word .doc를 만들어 각 서버 역할을 여러 개별 섹션으로 구성하려고 했습니다.
- 요약
- 유지 관리 요구
- 설치된 소프트웨어의 인벤토리
- 하드웨어 사용 가능
- 하드웨어 기본값
제가 알고 싶은 것은 이러한 컴퓨터에 대한 문서를 작성할 때 따를 수 있는 더 나은 템플릿이 있는지입니다. 나는 내가 만든 것이 무엇이든 필요하다면 다른 사람이 기계를 재구축할 수 있을 만큼 충분하기를 바라고 있습니다.
답변1
좋은 문서화 시스템을 위한 가장 중요한 사항은 다음과 같습니다.
- 업데이트하기 쉬움(또는 사람들이 업데이트하지 않아 쓸모없게 됨)
- 쉽게 액세스할 수 있습니다 - 어느 위치에서나 여러 장치에서 가능합니다.
- 잘 정리되어 있어 사람들이 필요한 정보를 쉽게 찾을 수 있고 동일한 정보의 중복이 최소화됩니다.
워드 문서를 사용해 보았습니다. 3점 모두 실패합니다. Word 문서는 업데이트하기 어렵고 결국 사람들이 다른 사본을 갖게 됩니다.
내가 사용하기 위해 찾은 최고의 시스템은 위키입니다. DokuWiki는 내 목적에 아주 잘 작동합니다. 어디서나 쉽게 액세스하고 업데이트할 수 있습니다.
내 위키에는 전체 네트워크 설정을 설명하는 페이지가 배치되어 있으며, 각 서버, 클러스터 및 애플리케이션에 대한 페이지로 연결됩니다. 이렇게 하면 특정 항목에 대한 모든 세부 정보가 별도의 페이지에 보관되고 관련된 모든 위치에서 링크될 수 있습니다. 무언가 변경되면 한 페이지에서만 변경하면 되며 내가 찾고 있는 정보를 쉽게 찾을 수 있습니다. 을 위한.
또한 네임스페이스 템플릿을 지정할 수 있으므로 새 서버 페이지를 만들 때 IP 주소, 하드웨어 구성 등을 입력할 수 있는 테이블이 미리 채워집니다. 모든 빈 필드에는 FIXME가 기록되어 있으므로 전체 위키를 검색할 수 있습니다. FIXME의 경우 문서에서 누락된 내용을 확인하세요.
정말 멋진 디자인을 원한다면 구성 파일과 같은 항목을 가져와 구문 분석하고 읽기 쉬운 형식으로 표시하는 플러그인을 작성할 수 있습니다. 예를 들어, 저는 네트워크 패치 패널에 대한 텍스트 설명을 가져와 각 포트가 가는 위치에 대한 레이블과 함께 그림을 그리는 PatchPanel이라는 플러그인을 작성했습니다.
http://blog.emsley.ca/2014/04/documentation.html내가 어떻게 설정했는지에 대한 더 완전한 글이 있습니다.