Chiến lược viết tài liệu kỹ thuật hiệu quả

Tôi đã viết về kỹ thuật thuộc loại này hay loại khác từ năm 1999, khi tôi đang làm QA cho chi nhánh R&D của Altec Lansing ở Kfar Saba, Israel. Hồi đó, chúng tôi đã đưa ra các thiết bị cải tiến, liên quan đến âm thanh như thiết bị âm thanh USB (thở hổn hển) hoạt động trên Windows ME và 2000. Chúng có nhiều lỗi và việc thiết lập chúng không phải là điều đơn giản như ngày nay.

Chúng tôi cần tài liệu.

Chúng tôi có một số vòng mà người dùng phải vượt qua và chúng tôi cần một cách để ghi lại chúng là gì, các trường hợp khó khăn là gì cũng như cách chẩn đoán và khắc phục tất cả những thứ đó. Nó cần được đóng gói đẹp mắt, được định dạng rõ ràng và có thể truy cập được đối với những người dùng đã cài đặt ứng dụng trợ giúp của chúng tôi. Tôi đã tìm thấy ứng dụng Robohelp, ứng dụng được sử dụng để tạo các ứng dụng trợ giúp tiêu chuẩn trên Windows và đã thêm tệp trợ giúp vào bản cài đặt của chúng tôi.

Trong quá trình đảm bảo chất lượng, chúng tôi sẽ xác định các vấn đề, ghi lại những gì chúng tôi cho là nổi bật và sắp xếp nó vào tệp trợ giúp đi kèm với thiết bị. Lúc đó tôi 19 tuổi và không có kinh nghiệm gì về những thứ này, và đó là một quá trình vô cùng ngây thơ. Tuy nhiên, tôi cảm thấy đó là điều đúng đắn cần làm cho người dùng của chúng tôi và người quản lý của tôi đã không yêu cầu tôi một cách rõ ràng là không làm vậy.

Đã 24 năm trôi qua và kể từ đó tôi đã làm tài liệu cho rất nhiều dự án. Quy mô đã tăng lên và cách tôi nhìn nhận những loại dự án đó đã thay đổi đáng kể.

Tôi có một số suy nghĩ về điều gì tạo nên tài liệu tốt và tôi muốn chia sẻ chúng với bạn nếu bạn quan tâm.

Khái niệm tài liệu cốt lõi

Tôi muốn bắt đầu với một bộ quy tắc cụ thể hơn mà tôi tin là rất quan trọng đối với sự thành công của sản phẩm tài liệu.

• Tài liệu nên sử dụng những từ nhỏ để mô tả những ý tưởng lớn - vì vậy, đừng sử dụng những từ hoa mỹ hoặc những câu phức tạp để mô tả những gì có thể nói bằng những thuật ngữ đơn giản hơn. Bạn sẽ mất đi người dùng trong quá trình viết và điều đó không xứng đáng với cái tôi của người viết.

• Tài liệu nên kể một câu chuyện khi bạn có thể - bởi vì một nhóm nhiệm vụ cá nhân, liên quan để kể một câu chuyện sẽ hấp dẫn và đáng nhớ hơn đối với người dùng của bạn hơn là một nhóm hướng dẫn trừu tượng.

• Tài liệu phải có thể tìm kiếm được - bởi vì nghiêm túc mà nói: đây là điều hiển nhiên. Nếu tài liệu của bạn không dễ tìm thấy nội dung, người dùng của bạn sẽ không tìm thấy thứ họ cần.

• Tài liệu hầu như luôn là một phần của chiến lược lớn hơn - và điều này đặc biệt đúng khi nói đến các sản phẩm phần mềm. Điều này đề cập đến chủ đề lớn hơn về sự ủng hộ của nhà phát triển, nhưng tóm lại: tài liệu của bạn phải được hỗ trợ bằng các hướng dẫn bằng video, ví dụ sử dụng thực tế và hỗ trợ kỹ thuật trực tiếp.

• Tài liệu nên được kiểm tra - vì bạn có thể chắc chắn rằng mọi thứ đều đúng nhưng nếu không có người dùng thực sự, giống như với bất kỳ sản phẩm nào khác, bạn sẽ không biết chắc chắn. Kiểm tra nó và kiểm tra lại.

  
  

Tài liệu toàn diện là sản phẩm được thiết kế tốt

Khi bạn học một ngôn ngữ lập trình mới, các khái niệm và ý tưởng từ ngôn ngữ đó sẽ tràn vào túi các thủ thuật giải quyết vấn đề của bạn. Nó giúp bạn trở thành một nhà phát triển phần mềm giỏi hơn và cuối cùng, bạn tạo ra phần mềm tốt hơn vì bạn nhận thức rõ hơn và có năng lực hơn.

Sự nghiệp của tôi rất phức tạp và bao gồm rất nhiều công việc thiết kế sản phẩm phần mềm, phát triển phần mềm, hỗ trợ kỹ thuật và vận động nhà phát triển. Mỗi ngành học đều ảnh hưởng đến cách tôi suy nghĩ và tiếp cận người khác.

Khi tôi tiếp cận một dự án Viết kỹ thuật, đó là với cái nhìn bao quát về những gì người dùng sẽ cần. Tôi nghĩ đó là cách đúng đắn để nghĩ về tài liệu: một cách tổng thể. Tài liệu không phải là một thứ được xác định rõ ràng và để tạo ra những tài liệu tốt, bạn phải linh hoạt.

Đối với tôi, điều đó có nghĩa là bạn phải nghĩ về người dùng của mình từ nhiều góc độ nhất có thể. Bạn không thể coi bất cứ điều gì là đương nhiên hoặc bạn sẽ khiến một số nhóm người dùng thất vọng theo cách sẽ tác động tiêu cực đến thương hiệu, sản phẩm hoặc doanh nghiệp của bạn theo cách khó có thể quay trở lại.

Tài liệu của bạn thường mang lại trải nghiệm thành công cho người dùng.

Nếu bạn làm tốt, người dùng sẽ sử dụng sản phẩm của bạn thành công và trở thành nhà vô địch cho thương hiệu của bạn. Nếu bạn không làm như vậy, họ có thể sẽ không bao giờ sử dụng sản phẩm của bạn nữa vì tài liệu của bạn đã để lại ấn tượng xấu trong tâm trí họ. Họ cũng sẽ cho người khác biết. Hoạt động tiếp thị tốt bắt đầu từ đây, vì vậy hãy ghi nhớ điều đó.

Làm tài liệu hay

Tạo tài liệu tốt chỉ đơn giản có nghĩa là bạn phải tiếp cận việc tạo tài liệu của mình giống như bất kỳ quy trình sản phẩm nào khác.

Bạn cần phải:

• Biết lý do bạn tạo tài liệu của mình
• Biết đối tượng mục tiêu của bạn là ai
• Biết điểm yếu của họ là gì
• Cải thiện tài liệu của bạn theo thời gian

Chúng ta hãy xem xét kỹ hơn về từng điều này.

Biết lý do tại sao tài liệu của bạn thường là một câu hỏi và câu trả lời thực sự đơn giản được đặt ra trên bề mặt của nó. Bạn đang tạo tài liệu vì nếu không, người dùng sẽ bỏ qua và không sử dụng được sản phẩm của bạn. Ở mức độ sâu hơn, có một câu trả lời cụ thể cho trường hợp sử dụng của bạn. Có một công cụ phát triển? Đó là một bộ câu trả lời. Có một công cụ thiết kế bán lẻ? Bạn có sản phẩm Kế toán SaaS? Bạn có máy pha cà phê tự động? Đây là tất cả các bộ câu trả lời riêng biệt.

Hình thức tài liệu của bạn được mô tả bởi người sẽ sử dụng nó. Nó có trực tuyến không? Nó có đi kèm với một ứng dụng không? Nó có được in không? Mọi cơ sở người dùng sẽ cần thứ gì đó khác và bạn phải xác định rõ họ là ai ngay từ đầu.

Công việc của bạn là tìm ra điều gì khó khăn đối với mỗi người dùng và tạo tài liệu của bạn để hướng họ thông qua nội dung giàu thông tin nhằm giải quyết vấn đề cụ thể của họ.

Quan trọng nhất, bạn phải biết rằng có thể bạn sẽ không làm đúng ngay lần đầu tiên. Điều đó có nghĩa là tài liệu của bạn cần được duy trì và cập nhật khi sản phẩm của bạn phát triển và thay đổi theo thời gian. Hy vọng rằng điều này được thực hiện trong một số khuôn khổ cho phép giao tiếp dễ dàng với những người dùng mà bạn đang cố gắng trợ giúp. Bạn phải nói chuyện với người dùng, lắng nghe nhu cầu của họ và cố gắng sử dụng tài liệu của bạn để cải thiện trải nghiệm của họ khi sử dụng sản phẩm của bạn.

Tài liệu của bạn là một phần không thể thiếu trong thành công của bạn

Tôi sẽ tóm tắt bằng cách nhấn mạnh tầm quan trọng của các tài liệu. Không có chúng, người dùng của bạn phải tự lo liệu và phải tự bảo vệ mình.

Điều này luôn có nghĩa là sẽ có ít trường hợp thành công hơn, lượt xem sản phẩm kém hơn trong hệ sinh thái của bạn, nhiều nhà phát triển hoặc người dùng không hài lòng hơn và tác động tiêu cực đến thương hiệu hoặc công ty của bạn.

Bản thân tài liệu là một sản phẩm phụ quan trọng, là một khoản đầu tư và phải là một phần trong chiến lược sản phẩm rộng hơn của bạn.