Tài liệu As-A-Manual so với Tài liệu As-A-Checklist

Tôi đã có các cuộc thảo luận trong quá khứ với những người khác trong bộ phận của tôi về tài liệu, cụ thể, mức độ chi tiết và yêu cầu. Theo quan điểm của họ, tài liệu là một danh sách kiểm tra đơn giản về những việc Y cần làm khi X gặp sự cố.

Tôi không đồng ý. Tôi nghĩ rằng điều này giả định rằng tất cả các vấn đề trong CNTT có thể dễ dàng được đưa vào danh sách kiểm tra đơn giản về quy trình phục hồi. Tôi nghĩ rằng nó hoàn toàn bỏ qua sự phức tạp của tình huống và vì những người khác trong bộ phận không phải lúc nào cũng hiểu sâu về vấn đề này (đó là lý do tại sao tôi viết tài liệu - vì vậy họ có điều gì đó để đề cập đến ) rằng tài liệu nên bao gồm một số tài liệu cơ bản, chẳng hạn như:

• Mục đích của hệ thống (phụ) trong câu hỏi
• Tại sao nó được cấu hình theo cách đó
• Mong đợi các sự kiện sẽ xảy ra khi cài đặt / thủ tục được thực hiện
• Các vấn đề tiềm ẩn có thể khiến thủ tục thất bại

Tuy nhiên, tôi khá hơn so với điều này, vì vậy tài liệu của tôi bắt buộc phải được viết lại thành một biểu mẫu có nội dung "Các bước ABC được áp dụng theo thứ tự sẽ giải quyết vấn đề X". Tôi thường nghe thấy những lời than thở rằng nó cần phải nằm gọn trên một trang giấy. Hãy thử giải thích cấu hình của Squid ACL cho ai đó theo cách này, bao gồm cả khắc phục sự cố, thông qua một tài liệu một trang. Đó chỉ là một trong nửa tá tài liệu "đang chờ được viết" dưới dạng danh sách kiểm tra phục hồi.

Là phương pháp tôi ủng hộ thực sự quá nhiệt tình? Hoặc họ đúng, và tôi chỉ nên quan tâm đến việc kinh doanh của mình ở đây và chỉ viết cho họ một danh sách kiểm tra đơn giản? Mối quan tâm của tôi là, cho dù bạn viết một danh sách kiểm tra thủ tục tốt đến đâu, nó thực sự không giải quyết được vấn đề đòi hỏi SysAdmin phải suy nghĩ kỹ. Nếu bạn đang dành thời gian thực hiện một danh sách kiểm tra các quy trình phục hồi mà cuối cùng không giải quyết được vấn đề (vì có những yếu tố bổ sung không phải là một phần của tài liệu, do trọng tâm hẹp của tài liệu ) và mục đích của tài liệu là để tránh đọc lại các trang man và wiki và các trang web một lần nữa, vậy tại sao tôi lại trải qua các chuyển động? Tôi chỉ lo lắng quá nhiều, hay đây là một vấn đề thực sự?

BIÊN TẬP:

Hiện tại không có vị trí trợ giúp trong bộ phận. Đối tượng cho các tài liệu sẽ là cho các quản trị viên khác hoặc cho người đứng đầu bộ phận.

Khi viết của tôi, tôi luôn luôn viết thành hai ba bộ. Danh sách kiểm tra được thực hiện, với phần phụ lục RẤT NHIỀU về kiến ​​trúc của hệ thống bao gồm lý do tại sao mọi thứ được thực hiện theo cách của chúng, các điểm dính có thể xảy ra khi trực tuyến và các giả định thiết kế trừu tượng. theo sau là một danh sách các vấn đề có thể xảy ra và các giải pháp của họ, tiếp theo là phần dài hơn với thông tin về cách thức hoạt động của một hệ thống, tại sao nó lại như vậy và thông tin khác hữu ích để chỉ cho mọi người đi đúng hướng.

Ở công việc cuối cùng của chúng tôi, chúng tôi được yêu cầu viết tài liệu để những người trợ giúp cấp 1 thậm chí có thể mang mọi thứ trở lại. Danh sách kiểm tra cần thiết này, thường đã hết hạn trong vòng 3 tháng sau khi viết. Chúng tôi được khuyến khích viết hướng dẫn xử lý sự cố bất cứ khi nào có thể, nhưng khi cây dự phòng có nhiều hơn ba nhánh trong đó, bạn không thể viết tài liệu đó mà không đi trừu tượng.

Khi rời khỏi công việc cuối cùng của mình, tôi đã lật lại 100 trang 'hướng dẫn cách làm công việc của mình' trước khi tôi rời đi. Nó có những thứ trừu tượng trong đó, triết lý thiết kế, cũng như các điểm tích hợp. Vì tôi có lẽ đang viết cho một sysadmin khác, người sẽ thay thế tôi, tôi đã nhắm nó vào một người có thể có những khái niệm trừu tượng và biến chúng thành những hành động cụ thể.

Năm năm đã trôi qua và tôi thấy ý kiến ​​của mình về điều này đã thay đổi phần nào. Cả Tài liệu dưới dạng Thủ công và Tài liệu dưới dạng Danh sách kiểm tra đều có những vị trí rất có giá trị trong hệ thống phân cấp tài liệu và cả hai đều cần được sản xuất. Họ nhắm mục tiêu đối tượng rất khác nhau, mặc dù.

Tài liệu dưới dạng Danh sách kiểm tra

Thị trường mục tiêu của loại tài liệu này là các đồng nghiệp muốn làm thế nào để làm một việc. Chúng có hai loại:

• Đồng nghiệp, những người chỉ muốn biết cách làm một việc và không có thời gian để xem qua hướng dẫn mười lăm trang và tự mình tìm ra các bước.
• Các thủ tục khá phức tạp trong các bước, nhưng chỉ cần được chạy một lần trong một thời gian.

Thiếu kiên nhẫn là người lái xe cho loại đầu tiên. Có thể đồng nghiệp của bạn không thực sự muốn biết lý do tại sao đầu ra phải được chuyển qua biểu thức chính quy perl 90 ký tự, chỉ là nó phải có để đóng vé. Chắc chắn bao gồm một câu như "Để được giải thích chi tiết về lý do tại sao quy trình công việc này trông như thế này, hãy theo liên kết này", trong danh sách kiểm tra cho những người muốn biết tại sao.

Điểm thứ hai là về các quy trình không chạy thường xuyên nhưng chứa những cạm bẫy. Danh sách kiểm tra hoạt động như một bản đồ để tránh Doom nhất định chỉ lướt qua nó. Nếu danh sách kiểm tra được giữ trong một tài liệu repo, nó sẽ tiết kiệm được việc tìm kiếm email trong thời gian quản trị viên cũ gửi một CÁCH.

Theo tôi tài liệu kiểm tra danh sách tốt cũng bao gồm các phần về các điểm thất bại có thể, và phản ứng với những thất bại đó. Điều này có thể làm cho tài liệu khá lớn và kích hoạt phản hồi TL; DR ở đồng nghiệp, vì vậy tôi thấy rằng việc tạo các chế độ thất bại và phản hồi của chúng là một liên kết từ danh sách kiểm tra thay vì trên chính trang đó tạo ra một danh sách kiểm tra không chính đáng. Ôm siêu văn hóa.

Tài liệu làm thủ công

Thị trường mục tiêu cho loại tài liệu này là những người muốn tìm hiểu thêm về cách hệ thống hoạt động. Tài liệu kiểu cách làm nên có thể được lấy từ tài liệu này, nhưng thông thường hơn tôi thấy nó là phần bổ sung cho tài liệu kiểu danh sách kiểm tra để sao lưu các quyết định đưa ra trong quy trình làm việc.

Đây là tài liệu mà chúng tôi bao gồm các phần nhai như:

• Giải thích tại sao nó được cấu hình theo cách này.
  • Phần này có thể bao gồm các vấn đề phi kỹ thuật như chính trị xung quanh cách toàn bộ thứ được mua và cài đặt.
• Giải thích các chế độ thất bại phổ biến và phản ứng của họ.
• Giải thích bất kỳ thỏa thuận cấp độ dịch vụ nào, cả bằng văn bản và trên thực tế.
  • De facto: "nếu điều này thất bại trong tuần chung kết thì đó là vấn đề của mọi thứ. Nếu trong kỳ nghỉ hè, hãy quay lại giấc ngủ và giải quyết nó vào buổi sáng."
• Đặt ra các mục tiêu nâng cấp và tái cấu trúc.
  • Chính trị có thể khác sau này, tại sao chúng ta không sửa một số ý tưởng tồi được đưa ra lúc đầu?

Tất cả đều rất hữu ích để có được sự hiểu biết toàn diện về toàn bộ hệ thống. Bạn không cần một sự hiểu biết toàn diện để chạy các nhiệm vụ tự động hóa đơn giản của con người, bạn cần nó để tìm ra lý do tại sao một cái gì đó đã phá vỡ nó và có một ý tưởng để làm cho nó không làm điều đó một lần nữa.

Bạn cũng đã đề cập đến tài liệu Phục hồi thảm họa phải là một danh sách kiểm tra.

Tôi hiểu, bạn có cảm tình của tôi.

Có, tài liệu DR không cần phải giống như danh sách kiểm tra càng tốt.
Có, tài liệu DR có khả năng chống lại danh sách kiểm tra nhất do có bao nhiêu cách để mọi thứ có thể phá vỡ.

Nếu danh sách kiểm tra DR của bạn trông giống như:

1. Gọi Dustin hoặc Karen.
2. Giải thích vấn đề.
3. Đứng lại.

Bạn có một vấn đề. Đó không phải là một danh sách kiểm tra, đó là một sự thừa nhận rằng sự phục hồi của hệ thống này rất phức tạp, cần một kiến ​​trúc sư để tìm ra. Đôi khi đó là tất cả những gì bạn có thể làm, nhưng cố gắng tránh nó nếu có thể.

Tài liệu DR lý tưởng chứa danh sách kiểm tra thủ tục cho một vài thứ khác nhau:

• Thủ tục xử lý để tìm ra những gì đã sai, điều này sẽ giúp xác định ...
• Thủ tục phục hồi cho các trường hợp thất bại nhất định. Được hỗ trợ bởi ...
• Kịch bản phục hồi được viết tốt trước để giúp giảm thiểu lỗi của con người trong quá trình khôi phục.
• Tài liệu hướng dẫn sử dụng về các trường hợp thất bại, tại sao chúng xảy ra và ý nghĩa của chúng.

Thủ tục xử lý đôi khi là tất cả các tài liệu DR bạn có thể thực hiện cho một số hệ thống. Nhưng có nó có nghĩa là cuộc gọi 4 giờ sáng sẽ trở nên dễ hiểu hơn và kỹ sư cao cấp thực hiện việc khôi phục sẽ có thể giải quyết vấn đề thực tế nhanh hơn.

Một số trường hợp thất bại có quy trình phục hồi thẳng. Tài liệu cho họ. Trong khi ghi lại chúng, bạn có thể tìm thấy các trường hợp trong đó danh sách các lệnh đang được nhập theo một thứ tự cụ thể, đây là trường hợp sử dụng tuyệt vời để viết kịch bản; nó có thể biến thủ tục phục hồi 96 điểm thành 20 điểm. Bạn sẽ không bao giờ biết liệu bạn có thể viết kịch bản gì đó cho đến khi bạn lập bản đồ hành động của quy trình khôi phục bằng hành động.

Tài liệu hướng dẫn sử dụng cho các trường hợp thất bại là điểm dừng cuối cùng được sử dụng khi không có quy trình khôi phục hoặc quy trình khôi phục không thành công. Nó cung cấp các gợi ý google cần thiết để có thể tìm người khác gặp vấn đề đó và họ đã làm gì để khắc phục nó.

Trên thực tế, chúng tôi cũng không sử dụng Tài liệu dưới dạng thử nghiệm

Điều đó đang được nói rằng chúng tôi đã có tài liệu bằng văn bản đi kèm với Tài liệu hướng dẫn . Chúng tôi đã có danh sách kiểm tra tại chỗ nhưng khi phát triển, chúng tôi thấy chúng dễ bị lỗi và thực sự thất bại trên toàn bộ hệ thống.

Tuy nhiên chúng tôi có loại "Tài liệu Như-một-Checklist" cài đặt, đó là - như đã đề cập ở trên - chúng tôi rộng rãi dõi các dịch vụ của chúng tôi. Có một câu nói:

Nếu bạn không theo dõi nó, bạn sẽ không quản lý nó

Điều đó hoàn toàn đúng, nhưng một điều khác nên là:

Nếu bạn không theo dõi nó, bạn sẽ không ghi chép lại

Bất cứ khi nào chúng tôi cần di chuyển các dịch vụ, chúng tôi chỉ cần giữ "Nhóm dịch vụ", "Nhóm máy chủ", bất cứ điều gì áp dụng (chúng tôi sử dụng Nagios, như bạn có thể đoán từ từ vựng) mở và nó không di chuyển miễn là có một điểm đỏ duy nhất trên bất kỳ dịch vụ nào.

Các xét nghiệm cung cấp một danh sách kiểm tra tốt hơn nhiều so với bất kỳ danh sách kiểm tra viết tay nào có thể cung cấp. Đó thực sự là tài liệu tự, ngay khi chúng tôi gặp một số lỗi không được theo dõi nhưng thử nghiệm ít nhất sẽ được thêm vào Nagios, với điều đó chúng tôi nhận được 2 Điều miễn phí:

• chúng ta biết khi nó thất bại
• một điểm khác trong danh sách kiểm tra

Tài liệu "thực" được lưu trong Wiki đề cập đến tỷ lệ cược và kết thúc của dịch vụ hoặc thử nghiệm cụ thể. Nếu nó bị thiếu, mọi người sẽ thêm nó ngay khi chúng tôi cần thực hiện một số di chuyển hoặc cần thực hiện một số công việc với nó, cho đến nay phương pháp đó đã hoạt động rất tốt.

Ngoài ra, tài liệu sai lệch cũng được giải quyết rất nhanh, mỗi khi có lỗi xảy ra, mọi người bắt đầu tra cứu tài liệu và cố gắng giải quyết vấn đề với HowTos trong đó, nếu nó sai chỉ cần cập nhật với phát hiện của bạn.

Chỉ cần nghĩ về các lỗi người ta có thể tạo ra bằng cách làm theo danh sách kiểm tra và không cài đặt bất kỳ thử nghiệm nào sẽ cung cấp cho bạn hộp kiểm màu xanh lá cây sau khi áp dụng chúng. Tôi không nghĩ có thể tách biệt Tài liệu khỏi Giám sát.

Nó phụ thuộc vào đối tượng mục tiêu cho tài liệu của bạn.

Đối với các loại trợ giúp (cấp 1), danh sách kiểm tra là cách chính xác để đi; Tất nhiên, điều này giả định rằng có mức độ hỗ trợ cao hơn với kiến ​​thức sâu hơn mà bạn mô tả.

Nếu tài liệu dành cho nhóm hệ thống, tôi luôn nhầm lẫn về phía tài liệu nhiều hơn. Thật khó để có tài liệu đầy đủ chỉ để có được, nếu ai đó (chính bạn) muốn viết tài liệu rộng lớn hơn với thông tin cơ bản cần thiết - không có cá nhân lành mạnh nào cản trở bạn!

Cá nhân tôi cố gắng và giữ tài liệu đơn giản nhất có thể. Nó có xu hướng bao gồm:

• Những gì [X] được cho là phải làm (yêu cầu).
• Làm thế nào [X] đã được cấu trúc ở mức cao (thiết kế).
• Tại sao tôi thực hiện [X] theo cách tôi đã làm (cân nhắc thực hiện).
• Cách triển khai [X] là không chuẩn (cách giải quyết).
• Các vấn đề phổ biến với [X] và cách giải quyết chúng (các vấn đề).

Vì vậy, thừa nhận phần các vấn đề phổ biến của tôi có thể là một mô tả ngắn gọn về những gì đã xảy ra và các điểm hướng dẫn về cách khắc phục nó.

Tôi thường giả định một số kiến ​​thức từ người đọc hệ thống trong câu hỏi (trừ khi nó đặc biệt phức tạp). Tôi không có thời gian để làm cho hầu hết các tài liệu kỹ thuật cấp 1 hoặc quản lý của tôi có thể đọc được - nhưng cấp độ 3 rõ ràng sẽ ổn.

Tôi nghĩ rằng nó rõ ràng phụ thuộc vào chủ đề. Không phải mọi thứ đều có thể được giảm xuống một danh sách kiểm tra đơn giản và không phải mọi thứ đều cần hướng dẫn sử dụng chi tiết.

Có vẻ như bạn đang nói về tài liệu nội bộ và theo kinh nghiệm của tôi, bạn không thể đưa ra một danh sách các bước, vì có quá nhiều sự lựa chọn. Ngay cả việc tạo tài khoản người dùng cũng có một số tùy chọn (trong môi trường của chúng tôi) để tài liệu "Tài khoản mới" của chúng tôi liệt kê các bước cơ bản theo thứ tự, nhưng đối với mỗi bước có một mô tả về các biến thể là gì.

Mặt khác, chúng tôi chưa bao giờ viết nhiều tài liệu cho "Cách vá trong văn phòng", nhưng tài liệu rất sơ sài của chúng tôi cũng không phải là một danh sách kiểm tra - nó đề cập đến quy ước chúng tôi sử dụng cho màu cáp, nhấn mạnh rằng bạn phải cập nhật bảng tính liệt kê các kết nối và đó là về nó.

Vì vậy, bây giờ tôi đã viết điều này, tôi hoàn toàn đồng ý: danh sách kiểm tra từng bước sẽ không cắt nó cho nhiều quy trình.

Tôi hoàn toàn đồng ý với bạn về điều này (ủng hộ tài liệu đầy đủ) một phần vì tôi đã quen với những người tiền nhiệm, những người KHÔNG quan tâm nhiều đến tài liệu. Như đã nói trong các bài viết liên quan, viết nó ra không chỉ tốt cho người khác, mà còn giúp bạn hiểu đầy đủ hơn về môi trường của bạn và củng cố nó trong tâm trí của chính bạn. Đó là một kết thúc cho chính nó.

Ở một khía cạnh khác, tôi thấy rằng rất nhiều sự phản hồi xuất phát từ một niềm tin kỳ quặc rằng tài liệu crappy / nonexistant = bảo mật công việc. Kiểu suy nghĩ đó có vẻ không trung thực và mờ ám.

Kudos cho bạn để bucko hiện trạng.

Tôi tài liệu khá nhiều, tôi thậm chí có một danh sách kiểm tra ưu tiên tài liệu :-), tuy nhiên tôi sẽ không ghi lại những thứ có thể được coi là kiến ​​thức chung chung (ví dụ mô tả tốt về vấn đề đưa ra câu trả lời trong trang đầu tiên của google).

Đối với bất kỳ ai quan tâm ở đây là danh sách kiểm tra tài liệu của tôi (hoạt động cho tôi, có thể không dành cho bạn, các nhận xét và đề xuất được đánh giá cao):

1. Tạo một nhật ký / nhật ký cá nhân mà bạn viết ra tất cả những gì bạn đã làm / kiến ​​thức khôn ngoan
2. Các dịch vụ, dịch vụ nào ở đâu, làm gì và được thực hiện cho ai (có thỏa thuận SLA nào không? Nên tạo ra dịch vụ nào?)
3. Máy chủ, máy chủ ở đâu, bao nhiêu tuổi và được viết khi nào
4. Như trên nhưng đối với thiết bị mạng, UPS và tương tự
5. Như trên nhưng cho tất cả các máy người dùng
6. Bố cục của mạng vật lý (cáp đi đến đâu, bao lâu và chất lượng đo được là bao nhiêu)
7. Tổng quan cấu hình của phần mềm và giấy phép cho máy chủ
8. Tổng quan cấu hình của phần mềm và giấy phép cho máy người dùng
9. Tổng quan cấu hình của thiết bị chuyển mạch, bộ định tuyến và phần cứng chuyên dụng khác
10. Hợp đồng và SLA của tất cả các bên ngoài mà dịch vụ của tôi trực tiếp phụ thuộc vào (ISP, tên miền, v.v.)
11. Thiết lập một hệ thống vé với wiki tích hợp để đặt tất cả những thứ trên vào đó.
12. Đối với mọi sự cố, hãy tạo một vé (ngay cả khi bạn chỉ sử dụng nó cho chính mình).
13. Tạo một kịch bản vào Chủ nhật tập hợp vé và nhóm chúng theo loại vấn đề.
14. Vào thứ Hai, hãy tạo một giải pháp tự động hoặc tài liệu hướng dẫn người dùng cuối cho vấn đề xảy ra nhiều nhất
15. Nếu thời gian cho phép, làm tiếp theo.
16. Nếu không có gì để làm, hãy tìm một công việc mới và đưa cho người thay thế nhật ký của bạn ;-)

Một danh sách kiểm tra là tốt, miễn là nó không giả vờ là tài liệu đầy đủ . Một vài tài liệu cuối cùng tôi viết có hai phần: XYZ cho Người dùng, bao gồm các ảnh chụp màn hình đẹp về cách sử dụng nó; và XYZ cho Quản trị viên hệ thống, bao gồm cách thiết lập và tại sao (thậm chí có thể bao gồm cả yêu cầu kinh doanh cho nó tồn tại), các bẫy cần tránh và một phần về khắc phục sự cố. Khắc phục sự cố là nơi tôi muốn tìm danh sách kiểm tra. Có lẽ viết danh sách kiểm tra dưới dạng XYZ cho Hỗ trợ Công nghệ có thể giúp tạo điểm nhấn.

Bây giờ, đọc giữa các dòng, chỉ tập trung vào danh sách kiểm tra cho tôi thấy thiếu suy nghĩ "Bức tranh lớn" và kế hoạch dài hạn mà tôi mong đợi từ một người: chỉ từng thực hiện hỗ trợ công nghệ; hoặc một quản trị viên cơ sở chỉ mới bắt đầu; hoặc quá mải mê với công việc, họ không có thời gian để nghĩ về nó; hoặc chưa bao giờ bị thúc đẩy để suy nghĩ về nó; hoặc chỉ đơn giản là không quan tâm. Tôi không biết cái nào trong số này, nếu có, áp dụng trong trường hợp của bạn.

Tôi khá lớn về tài liệu. Công ty nơi tôi làm việc bây giờ cảm thấy rằng tài liệu là quan trọng, nhưng một số người trong công ty cảm thấy họ không có thời gian để viết tài liệu. Điều này có thể làm cho cuộc sống khó khăn cho bất cứ ai ngoài người ban đầu đã làm điều đó.

Đối với một số điều nhất định, tôi đã viết hướng dẫn từng bước. Bạn có thể gọi đây là danh sách kiểm tra nếu bạn muốn, nhưng nó không thực sự có ý định kiểm tra thực tế. Tôi gọi phong cách tài liệu của mình là "các bước mẫu giáo". Nó theo khuôn mẫu sau một cuốn sách bài tập MCSE mà tôi đã có cho một trong các kỳ thi Windows 2000. Các bước rất chi tiết, nhưng việc sử dụng chữ in đậm / in nghiêng / kiểu chữ giúp bạn dễ dàng tô bóng và chỉ cần chọn ra những phần quan trọng để bạn không cần phải đọc mọi thứ sau khi bạn đã học các bước.

Một số điều không phù hợp với hướng dẫn từng bước, vì vậy tôi cố gắng cung cấp càng nhiều dữ liệu cấu hình càng tốt. Một số người có khuynh hướng kỹ thuật cuối cùng vẫn duy trì con đường sẽ có ý tưởng tốt hơn về những gì họ đang chống lại, và hy vọng nó sẽ làm cho cuộc sống của họ dễ dàng hơn một chút khi có sự cố.