Bắt đầu với tài liệu

Chúng tôi đã không làm bất kỳ tài liệu tại nơi làm việc của tôi. Tôi hoàn toàn mới với nó và yêu cầu một số hướng dẫn bắt đầu.

Tôi có một vài câu hỏi:

• Các tài liệu cần thiết mà một sysadmin nên viết và duy trì là gì? Và tại sao những điều này rất quan trọng?

• Làm thế nào để bạn giữ tài liệu của bạn đồng bộ với hệ thống? Làm thế nào để bạn giảm thiểu trùng lặp thông tin?

• Hướng dẫn đề xuất, thực hành tốt nhất, chống mẫu?

từ năm 2003 tôi đang ghi lại tất cả mọi thứ trong wiki kênh của chúng tôi.

Máy chủ

• thông số kỹ thuật phần cứng
• thông tin bảo hành
• thông tin mạng
• và tất nhiên cài đặt phần mềm và cấu hình

Quy trình làm việc

ví dụ: cách thêm hoặc xóa người dùng và cấp cho người đó quyền truy cập vào tất cả các dịch vụ có liên quan

Liên kết quan trọng

• liên kết đến tất cả các giao diện web của bạn
• liên kết đến các URL giám sát (nagios, munin, giám sát apc ...)
• liên kết đến wiki (cho phiên bản in!)

Hướng dẫn khẩn cấp

Phải làm gì nếu máy chủ mạng nội bộ / internet / máy chủ web / v.v.

Quan trọng:

Chọn một công cụ wiki dễ dàng xuất sang PDF!
Nó không hữu ích nếu bạn đang trong kỳ nghỉ, máy chủ chạy wiki của bạn bị hỏng và không ai biết phải làm gì vì tài liệu của bạn đang ngoại tuyến

Hãy xem twiki, docuwiki hoặc mediawiki.

BTW:

có một plugin OpenOffice.org để viết trực tiếp lên mediawiki - rất tiện lợi.

CHỈNH SỬA:

Nó cũng tốt đẹp để viết ra một số infos để /home/adminuser/maintenance. Điều này được thực hiện nhanh chóng và có thể rất hữu ích, nếu một số quản trị viên làm việc trên máy chủ. ví dụ:

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.

Trong khi bạn nhận ra rằng trong khi mọi người muốn (và cần) tài liệu, bạn cũng cần nhận ra rằng không ai có thời gian để đọc và nghiên cứu nội dung.

Vì vậy, đừng viết tài liệu cần nghiên cứu - thay vào đó, hãy cấu trúc tài liệu của bạn theo cách cho phép ai đó nhanh chóng tìm thấy thông tin họ cần, khi họ cần - có thể là trong khi hệ thống ngừng hoạt động và CTO thì thở xuống cổ anh ấy / cô ấy.

Với ý nghĩ này, một số gợi ý ...

• Tránh các khối văn bản lớn
• Danh sách Bullet là bạn của bạn
• Một sơ đồ rõ ràng là vàng
• Lặp lại là một ý tưởng tốt (1)
• Giúp dễ dàng cập nhật và mở rộng

(1) Đừng tạo ra một nguồn sự thật và buộc mọi người săn lùng nó. Ý tưởng càng quan trọng, bạn càng nên lặp lại nó.

Tài liệu cần thiết:

• Tài liệu máy chủ - thông số kỹ thuật / bố trí đĩa / phần mềm đã cài đặt / bất cứ điều gì cần lưu ý
• Các thủ tục thông thường - bất cứ điều gì được thực hiện không 'tầm thường' nên có một quy trình được ghi lại, đặc biệt nếu đó là những việc chưa được thực hiện trước đó.

Giữ tài liệu đồng bộ có thể khá nhiều 'sửa nó khi bạn thấy lỗi'. Cùng với điều này cần phải nhận ra rằng tài liệu có thể và sẽ lỗi thời, và nó không nên được theo dõi một cách mù quáng mà không tính đến điều này. Tài liệu có mặt để hỗ trợ quản trị viên trong các nhiệm vụ, không phải là một bộ quy tắc từng bước thay thế tư tưởng phê phán.

Giảm thiểu trùng lặp - sử dụng một cái gì đó như wiki mà bạn có thể liên kết tài liệu với nhau có thể giúp với điều này, thay vì lặp lại thông tin, bạn chỉ cần liên kết với nó. Vấn đề là người viết tài liệu cần phải biết rằng thông tin họ sắp sao chép đã tồn tại. Đây thường là một câu hỏi của tổ chức tốt.

Tôi đã thấy rằng việc tạo một mẫu là một trợ giúp lớn. Trong trường hợp của tôi, đó là một mẫu Word nhưng sử dụng bất kỳ bộ nào. Tạo một tệp bộ xương, hoàn thành với bảng mục lục và các phần như mong muốn. Sau khi bạn đã sử dụng một vài lần và thực hiện bất kỳ điều chỉnh tinh chỉnh nào, bạn sẽ tạo tài liệu mới nhanh hơn nhiều. Tính nhất quán của định dạng sẽ là một trợ giúp tuyệt vời, cả cho việc tạo tài liệu và sử dụng sau này. Tài liệu cần được lưu trữ ở nơi hợp lý và trong cấu trúc thư mục logic.

Cá nhân tôi phản đối sự lặp đi lặp lại vì thực tế đơn giản là nó khiến việc bảo trì trở nên khó khăn và tốn thời gian không cần thiết. Thay vì các tài liệu trùng lặp, hoặc các phần của tài liệu, hãy tạo các tham chiếu đến các tài liệu khác khi thích hợp. Nếu có điều gì đó thay đổi, bạn không bao giờ phải thay đổi tài liệu liên quan nhiều hơn một lần hoặc ở nhiều nơi, nếu không, bạn sẽ có một bộ sưu tập các tài liệu mâu thuẫn, không giúp được ai.

Trong khi tạo tài liệu của bạn chỉ cần ghi nhớ những gì nó làm. Ai đó sau này sẽ cần phải sử dụng nó. Nó sẽ có thể được sử dụng để làm công việc mà không có kiến ​​thức trước?

Không phải là một câu trả lời trực tiếp cho câu hỏi của bạn, mà là một con trỏ đi đúng hướng:

Tôi thấy Thực hành Quản trị Hệ thống và Mạng , bởi Limoncelli và Hogan (còn gọi là Kinh thánh Sysadmin) khá có giá trị vì đó là về các vấn đề "thực tiễn tốt nhất", chẳng hạn như tài liệu. Nếu bạn chưa biết về nó, hãy chắc chắn rằng bạn điều tra nó bất cứ khi nào bạn có cơ hội.

Đối với tôi, sự cân nhắc quan trọng nhất là làm cho nó dễ sử dụng. Nếu nó khó phối hợp thì mọi người sẽ tránh nó. Tôi chọn wiki của Trac làm phương tiện cho tài liệu của chúng tôi vì những lý do sau:

• Nằm ở trung tâm.

  Nhiều hơn một bản sao hoạt động của bất kỳ một tài liệu dẫn đến nhầm lẫn. Nếu bạn có thể giới thiệu mọi người đến cùng một địa điểm, cả người đóng góp và đối tượng, thì bạn có thể đơn giản hóa quy trình.

• Chỉnh sửa và định dạng đơn giản.

  Quá nhiều thời gian bị lãng phí cho các mẫu Word đẹp và phù hợp với phong cách của tác giả cuối cùng. Nếu bạn không làm mọi người thất vọng với điều này, thì việc chỉnh sửa khi đang di chuyển sẽ dễ dàng hơn và những người đóng góp có xu hướng làm như vậy nhiều hơn. Tách các mục nhiều như bạn muốn với TracLinks.

• Lịch sử kiểm toán.

  Điều quan trọng là phải biết ai đã tạo ra những gì thay đổi, khi nào và tại sao. Nếu bạn có thể buộc nó vào vé yêu cầu thay đổi và cấu hình cam kết nhật ký thì thậm chí còn tốt hơn. SVN cam kết móc là tuyệt vời cho việc này.