Các lỗi thường gặp trong Tài liệu do kỹ sư tác giả và cách khắc phục chúng

Trong sáu tháng qua, nhóm phát triển của chúng tôi đã áp dụng cách tiếp cận "tài liệu dưới dạng mã" (bạn có thể tìm hiểu thêm về hành trình của chúng tôi trong phần này ). Thường xuyên xem xét tài liệu do các đồng nghiệp của tôi từ Bộ phận Công nghệ tạo ra, tôi đã biên soạn một danh sách các vấn đề phổ biến nhất được tìm thấy khi viết tài liệu kỹ thuật.

Trong bài viết này, tôi sẽ chỉ cho bạn cách khắc phục những vấn đề này bằng cách sử dụng các công cụ của phương pháp tiếp cận “docs-as-code”.

Vấn đề 1. “Việc viết tài liệu không thuộc trách nhiệm của chúng tôi”

Xử lý tài liệu trên cơ sở đặc biệt giống như tự bắn vào chân mình cho toàn bộ nhóm phát triển. Nếu nhóm thiếu năng lực, thì đó là lý do thuyết phục để thực hiện việc bảo trì tài liệu dựa trên công nghệ và có thể dự đoán được.

Sửa chữa:

• Tích hợp cách tiếp cận “tài liệu dưới dạng mã” để phát triển tài liệu. Bằng cách này, bạn có thể cập nhật tài liệu lặp đi lặp lại, cùng với cơ sở mã, mà không có nguy cơ tích lũy nợ kỹ thuật.
• Phát triển hoặc tích hợp một không gian hoặc một nền tảng có thể hiển thị các tài liệu công nghệ và phục vụ như một nguồn thông tin duy nhất.
• Sử dụng môi trường phát triển tích hợp (IDE). Một IDE cho phép bạn kết hợp các plugin và tạo các tập lệnh tùy chỉnh để phát triển tài liệu. là một công cụ tuyệt vời để viết tài liệu, nhưng bạn có thể có các ứng dụng yêu thích của mình.
• Cài đặt plugin kiểm tra chính tả để bảo vệ khỏi lỗi chính tả. Thêm plugin vào IDE của bạn là một quá trình nhanh chóng và dễ dàng.
• Áp dụng các nguyên tắc nội bộ do công ty của bạn xây dựng đặc biệt, có tính đến thông tin chi tiết từ cộng đồng viết kỹ thuật (nếu bạn có), để thiết lập một phương pháp tiêu chuẩn hóa để phát triển tài liệu trong công ty. Thực hiện theo các hướng dẫn này sẽ hợp lý hóa quy trình lập tài liệu, tiết kiệm thời gian suy nghĩ về những gì và cách viết chính xác.
• Tự động kiểm tra dựa trên các hướng dẫn để giảm hoặc loại bỏ đáng kể thời gian xem xét tài liệu.
• Mẫu mọi thứ có thể và đồng ý với nhóm về tiêu chuẩn hóa các thành phần tài liệu.

Tôi sẽ cung cấp các tài nguyên có giá trị giúp bạn tự tin hơn khi làm việc với tài liệu kỹ thuật. Tôi tin rằng những tài nguyên này đủ toàn diện để trang bị cho bạn cách xử lý các tài liệu kỹ thuật một cách hiệu quả:

• Các " " phục vụ như một sổ tay toàn diện cho tài liệu dành cho nhà phát triển. Nó bao gồm mọi thứ bạn cần biết về định dạng, dấu câu, liệt kê và thêm các khối mã. Hướng dẫn này là đủ và là một tài liệu tham khảo có giá trị để phát triển các nguyên tắc nội bộ của chúng tôi, từ đó chúng tôi đã mượn một số thực hành tốt nhất.
• “ " là cuốn sách phải đọc cho bất kỳ ai tham gia làm việc với tài liệu dành cho nhà phát triển, cho dù họ đang phát triển, viết hay duy trì nó. Cuốn sách có sự góp mặt của một số tác giả nổi tiếng và được kính trọng trong lĩnh vực viết kỹ thuật.

• " " của Anne Gentle, một nhà văn kỹ thuật, là một hướng dẫn thực tế giới thiệu văn hóa tài liệu trong OpenStack. Thông qua các ví dụ thực tế, tác giả giải thích lý do tại sao tài liệu nên được quản lý trong GitHub và cách triển khai các quy trình công nghệ để tạo tài liệu hiệu quả. Cuốn sách cũng cung cấp các giá trị có giá trị hiểu biết sâu sắc về cách viết tài liệu chuyên nghiệp, bất kể bạn là nhà phát triển hay nhà văn kỹ thuật.

• Tôi cũng sẽ đề cập đến các nguyên tắc nội bộ để viết tài liệu kỹ thuật, bao gồm các mẫu và quy tắc định dạng. Những hướng dẫn như vậy tồn tại trong mọi công ty. Thông thường, chúng được phát triển với sự cộng tác của một nhà văn kỹ thuật tiên phong và nhà vô địch tài liệu nhà phát triển và phát triển khi văn hóa tài liệu trong nhóm phát triển.

Vấn đề 2. Viết tài liệu một mình

Chỉ phát triển toàn bộ tài liệu và sau đó gửi nó để xem xét có nguy cơ tạo ra tài liệu dư thừa hoặc không liên quan có thể không phù hợp với mục đích đã định.

Sửa chữa:

• Luôn bắt đầu với một bản phác thảo và chia sẻ nó với trưởng nhóm, chủ sở hữu sản phẩm, người viết kỹ thuật hoặc bất kỳ đồng nghiệp nào sẵn sàng đưa ra ý kiến chuyên môn của họ.
• Viết từng bước và chỉ định các yêu cầu kéo để xem xét trên cùng các đồng nghiệp đã đề cập ở trên.
• Thu thập và làm việc trên thông tin phản hồi.
• Hãy xem xét các ý kiến. Và hãy thoải mái với giọng điệu đánh giá, đôi khi nó có thể gay gắt, nhưng đó chỉ là một đặc thù của quá trình đánh giá.
• Đừng bỏ qua luồng tài liệu. Dưới đây là quy trình chung được áp dụng trong công ty của chúng tôi, nhưng các tính năng của quy trình này có thể phụ thuộc vào nhóm phát triển cũng như công ty:

Vấn đề 3. “Cần hiểu sẽ hiểu”

Thỉnh thoảng tôi nghe từ các nhóm: “Tôi đang viết cho nhóm phát triển", "những người cần hiểu sẽ hiểu", "đây là cách nó đã phát triển trong lịch sử nhóm của chúng tôi".

Nhưng biệt ngữ chuyên môn và Anh ngữ đòi hỏi sự phù hợp và thống nhất. Việc sử dụng chúng quá nhiều có thể dẫn đến tài liệu giống như ghi chú của một kỹ sư điên.

Đối với tài liệu, hãy sử dụng các từ và cấu trúc đơn giản nhất có thể. Một trong những nguyên tắc chính là viết để cuộn. Tài liệu có thể là một thách thức để viết vì nó thường rộng rãi, nhưng người đọc hiếm khi xem qua nó từ trang này sang trang khác. Thay vào đó, họ có xu hướng cuộn hoặc sử dụng tìm kiếm từ khóa. Do đó, văn bản phải dễ hiểu khi được mở từ bất kỳ phần nào.

Sửa chữa:

• Kiểm tra các thuật ngữ tiếng Anh và biệt ngữ chuyên môn bằng từ điển và các quy tắc hiện hành (hoặc đơn giản là Google chúng). Nếu một từ tồn tại trong từ điển, hãy viết theo các quy tắc chính tả ngôn ngữ của bạn.
• Nếu từ đó không có trong ngôn ngữ, hãy viết nó bằng ngôn ngữ gốc và cung cấp bản dịch sang ngôn ngữ của bạn trong ngoặc đơn.
• Thêm từ vào phần thuật ngữ và từ viết tắt vào danh sách từ viết tắt và từ viết tắt. Điều này đặc biệt quan trọng đối với các từ viết tắt "độc quyền" (dù có đề cập hay viết nhiều về PO đến đâu thì ý nghĩa của nó vẫn là một trong những câu hỏi phổ biến khi đọc tài liệu).
• Tính nhất quán – tuân theo phong cách viết đã chọn và các chữ viết tắt trong toàn bộ tài liệu (tốt hơn cho tất cả các tài liệu có sẵn trong công ty của bạn).
• Lập kế hoạch điều hướng tài liệu một cách cẩn thận. Cần có một cách nhanh chóng để tìm phần liên quan mà không cần phải đọc toàn bộ tài liệu. Do đó, điều cần thiết là cấu trúc nội dung một cách chu đáo với các tiêu đề rõ ràng và ngắn gọn. Các mẫu tài liệu nội bộ nên được phát triển để đơn giản và thuận tiện.

Vấn đề 4. Viết tài liệu đồng thời ở nhiều nơi

Đối với tài liệu, việc có một nguồn thông tin xác thực duy nhất – một không gian nơi bạn có thể tìm thấy thông tin cần thiết mà không phải lo lắng về tính chính xác của nó là rất quan trọng. Đối với tài liệu kỹ thuật của chúng tôi, một nền tảng được phát triển nội bộ đóng vai trò như một không gian như vậy. Tránh phân mảnh tài liệu trong các không gian khác nhau là điều cần thiết để tránh gây hiểu lầm cho bất kỳ ai bằng thông tin lỗi thời.

Sửa chữa:

• Trước khi xuất bản tài liệu công nghệ ở bất kỳ đâu, hãy đảm bảo rằng tài liệu đó không tồn tại ở nơi nào khác, nếu có thông tin cho rằng công ty sử dụng một số không gian để chia sẻ kiến thức.
• Lưu trữ hoặc xóa (nếu bạn có quyền sở hữu) tài liệu kỹ thuật lỗi thời. Nếu bạn lo lắng về việc xóa sớm (ví dụ: do các liên kết bên ngoài tới trang), hãy thêm chú thích cho biết rằng trang đã lỗi thời và vị trí tài liệu hiện tại của các tài liệu hợp lệ, nơi cần thực hiện các cập nhật tiếp theo.
• Nếu bạn bắt gặp thông tin hoặc thông tin chi tiết có giá trị, hãy thêm chúng vào tài liệu. Đừng để nó trong Slack hoặc bất kỳ nơi nào khác, đặc biệt là trong các cuộc trò chuyện riêng tư. Kiến thức đáng chia sẻ!

Đăng bởi Anna Goncharova