Tài liệu ra khỏi tất cả mọi thứ.
Gần đây có một chủ đề trên Slashdot về việc bắt đầu tài liệu, điều này đã thôi thúc tôi viết ra những suy nghĩ của mình về tài liệu.
Điểm chính của tôi là:
Nguyên tắc số 1: Không bao giờ được thực hiện
Tài liệu là một nỗ lực đang diễn ra sẽ luôn bị tụt hậu so với những gì trong sản xuất. Các thay đổi được thực hiện đột xuất, mọi thứ được di chuyển xung quanh hoặc ngừng hoặc đưa vào phục vụ một cách ngẫu nhiên. Tài liệu sẽ không bao giờ theo kịp.
Bạn phải bán cho những người trả các hóa đơn dựa trên giá trị của thời gian chi tiêu (và do đó, tiền) để giữ cho tài liệu chạy được cập nhật. Những cuộc trò chuyện đó thường diễn ra như sau: "hãy nhớ khi tôi phải chi $ TIME để tìm hiểu xem $ THING đã bị phá vỡ như thế nào? Khi tôi kết thúc, có một ghi chú công nghệ chi tiết về $ THING, để anh chàng tiếp theo sẽ không phải tìm ra tất cả. "
Bạn phải làm điều đó, mặc dù bạn sẽ không bao giờ hoàn thành.
Nguyên tắc số 2: Điều duy nhất tệ hơn là không có tài liệu là tài liệu sai
Đây là một sự thật hơn là một nguyên tắc. Tài liệu có thể đưa bạn vào cảm giác sai lầm rằng một cái gì đó đang ở trạng thái đã biết và nếu có sự cố xảy ra, do đó bạn có thể bắt đầu chạy để sửa nó.
Điều quan trọng là phải thừa nhận vấn đề này.
Nguyên tắc số 3: Bạn đang viết tài liệu cho người kế nhiệm
Tỷ lệ cược là 95% của bất cứ điều gì bạn làm tài liệu bạn sẽ không bao giờ phải tham khảo lại. Tài liệu là một bộ sưu tập trí tuệ cho tương lai, không phải cho bạn. Vì vậy, bạn phải giả định rằng khán giả của bạn biết rất ít hoặc không biết gì về các chi tiết cụ thể về cách mọi thứ diễn ra như thế nào.
Và sẽ có một người kế vị. Tôi không biết về bạn, nhưng tôi không có kế hoạch ở trong những môi trường cụ thể này cho đến hết đời. Cơ hội đến và đi, và khi chúng đến, đôi khi bạn đi. Nhưng cuộc sống vẫn tiếp tục ở phía sau bạn, và bạn càng có thể làm cho cuộc sống của mình thành công tốt đẹp hơn. Nếu không, bạn có thể có một bộ sưu tập các khách hàng cũ, những người lặng lẽ nói những điều không hay về bạn. Tôi muốn nói rằng đó là cùng 50 người làm việc ở khắp mọi nơi trong CNTT ở Ottawa vì bạn tiếp tục gặp họ ở khắp mọi nơi. Giúp người kế vị của bạn có thể mở ra cánh cửa cho bạn trong tương lai.
Bây giờ đến một mức độ nhất định, luôn có một mức độ "đổ lỗi cho anh chàng trước" khi rắc rối xuất hiện. Đó là một phần của kinh doanh. Tôi đã tự làm nó. Nhưng trong một số lần khi tôi đã nói xấu anh chàng trước đó như một kiểu biến thái, tôi đã học được cách khác rằng anh ta thực sự có hành động của mình với nhau và biết nhiều hơn về những gì đang xảy ra so với lúc đó.
Nguyên tắc số 4: "Tại sao" thường quan trọng hơn "Làm thế nào"
Khi nhìn vào một hệ thống, hầu hết chúng ta bắt đầu nghĩ rằng tại sao lại như thế này? Hầu như luôn luôn có những lý do rất cụ thể cho các lựa chọn cấu hình được thực hiện. Trong những trường hợp này, "Tại sao" ra lệnh "Làm thế nào" và bạn phải đảm bảo rằng người đọc hiểu được các vấn đề cụ thể đang được giải quyết khi kiểm tra việc hút thuốc vẫn là giải pháp của bạn.
Nguyên tắc số 5: Nó phải dễ dàng hoặc bạn sẽ không làm điều đó
Điều này có nghĩa là bạn phải rất ý thức về các công cụ của mình cũng như những người sẽ sử dụng các công cụ của bạn.
Giữ cho mọi thứ cập nhật phải dễ dàng. Nếu bạn phải thực hiện bất kỳ nỗ lực nào, thì bạn sẽ tìm thấy lý do để tránh làm điều đó khi nó được thực hiện tốt nhất, ngay lập tức sau khi thay đổi.
Nếu công cụ của bạn không dễ sử dụng, thì họ sẽ không sử dụng nó. Điều này có thể đặc biệt làm tê liệt trong môi trường nhóm, vì nhóm càng lớn thì càng có nhiều khả năng bạn sẽ gặp một thành viên trong nhóm không thích lựa chọn công cụ của bạn.
Cá nhân, tôi thích một wiki cho các tài liệu. Tuy nhiên, vấn đề là wiki không bắt buộc một cấu trúc đối với bạn, do đó cấu trúc phải được áp đặt từ bên ngoài. Điều này luôn dẫn đến xung đột ở đâu đó vì người khác có ý tưởng tốt hơn / khác biệt hơn.
Ở một số nơi tôi đã sử dụng các tài liệu Word và Visio "xuất bản" thành PDF, với bản PDF "mới nhất" được coi là có thẩm quyền. Điều này tốt ở chỗ bạn có một bộ sưu tập mà bạn có thể trao cho chủ nhân / người kế nhiệm. Các tệp PDF, nếu được ghi đúng ngày, có thể cung cấp một bản ghi lịch sử về những gì đã xảy ra, mặc dù một bản không dễ điều hướng. Thật tệ khi tôi không thích Word hay Visio và đã bị buộc phải có hiểu biết cơ bản về các công cụ này để truyền đạt ý tưởng một cách hiệu quả.
Chủ nhân hiện tại của tôi đang chơi đùa với ý tưởng về các tài liệu Word trong một cổng thông tin Sharepoint. Chúng ta sẽ phải xem chúng ta đến đó bao xa