Một số mẹo hay giúp nâng cao kĩ năng viết tài liệu kỹ thuật

Nếu bạn đang phát triển một trang web hay một sản phẩm phần mềm nào đó thì chắc chắn sẽ có lúc bạn phải viết lách. Mặc dù bạn là một designer, một developer,... chứ không phải một nhà văn.

Một ví dụ điển hình đó là, gần như ai cũng phải viết những tài liệu như file REAME, tài liệu hướng dẫn cài đặt môi trường, tài liệu giới thiệu phần mềm, hướng dẫn sử dụng cho người dùng hay file trợ giúp, những câu hỏi thường gặp... hoặc bạn cũng có thể sẽ phải viết những tài liệu như lời giới thiệu về trang web của bạn trên trang chủ, trang thông tin giới thiệu về nội dung trang web hoặc một bài viết trên blog cá nhân.

Dù không muốn nhưng ít nhiều chúng ta đều cần phải vận dụng kĩ năng viết lách.

Có thể nhận thấy ở bài viết của nhiều người, đang thiếu đi một số điểm dù rất nhỏ thôi nhưng dễ dàng thấy được và có tầm ảnh hưởng không nhỏ đến nội dung truyền đạt. Những điểm này có thể ngay lập tức cải thiện trải nghiệm, mức độ hiểu và hứng thú của người đọc về một bài viết về kĩ thuật. Bạn không cần phải là một chuyên gia để viết bài trên web, bạn chỉ cần có thể viết tốt vừa đủ là được.

Sau đây là một số gợi ý để bài viết của bạn có thể trở nên thú vị, dễ tiếp cận và dễ hiểu hơn:

Hãy viết một cách "con người" chứ đừng viết như một cái máy

Đừng ngại thể hiện sự hài hước, sáng tạo và thậm chí là ngốc ngếch. Việc thể hiện cái tôi, cá tính trong bài viết làm nên điểm nhấn. Độc giả sẽ cảm thấy bài viết của bạn thú vị hơn nhiều khi cách hành văn của bạn gần gũi, tự nhiên giống như đang giao tiếp trò chuyện với họ, thay vì ra lệnh, chỉ dẫn.

Trong cuốn sách "Hello Web App", tác giả đã viết lời giới thiệu như sau:

Dành tặng cho gia đình của tôi:

Andrey, người hỗ trợ tuyệt vời nhất mà ai cũng có thể nhờ được.

Westley, chú mèo nặng hơn 11kg, to bé nhất, xấu tính nhất nhưng lại đáng yêu nhất.

Molly, chú chó duy nhất mà tôi yêu thích ngoại trừ việc nó tè lên giường tôi đêm qua.

Chết tiệt!

Mục đích của việc sử dụng những từ ngữ đời thường và không trang trọng là để độc giả cảm nhận được rằng cuốn sách này không phải một cái gì đó quá nghiêm túc, mà sẽ rất gần gũi, thân thiện và vui vẻ. Bản thân cuốn sách "Hello Web App" là một cuốn sách về đề tài kĩ thuật, hướng tới việc thu hút người đọc tìm tòi về việc lập trình (một công việc khá là đáng sợ, kinh hoàng), nên việc tỏ ra hài hước và ngốc ngếch ngay từ đầu sẽ cho độc giả một cái nhìn và suy nghĩ rằng việc lập trình thực ra cũng có thể là một việc rất thú vị.

Bạn có thể thấy từ "Woohoo!" ở cuối đoạn văn mô tả khiến bài viết trở nên thân thiện và dễ tiếp cận hơn hẳn. Đa số độc giả đều đánh giá cao cuốn sách vì thấy nó rất đời thường và cách truyền đạt của tác giả giống như đang trò chuyện vậy. Việc này khuyến khích họ đọc hết cuốn sách và tạo được hứng thú với việc lập trình.

Hãy nhớ rằng những người đọc không hoàn toàn giống bạn

Việc này xảy ra rất nhiều ở những bài viết dành cho những đối tượng ở trình độ "nâng cao". Người viết thường có xu hướng cho rằng việc thao tác với project của họ đòi hỏi một trình độ hiểu biết nhất định. Nên người thao tác đó sẽ biết hết những điểm căn bản rồi. Vì thế họ thường xuyên bỏ qua những giải thích và hướng dẫn khi đề cập tới 1 nội dung mở rộng.

Tuy nhiên, có rất nhiều người trở thành "chuyên gia" bằng nhiều cách khác nhau nên việc mặc định người đọc đã biết hết các khái niệm rất nguy hiểm. Bạn có thể sẽ loại trừ rất nhiều đối tượng độc giả khi bỏ qua những chỉ dẫn. Nếu chỉ vì dự án của bạn là dành cho những developer với nhiều năm kinh nghiệm, thì cũng không có nghĩa là tất cả độc giả phải có cùng 1 cấp độ hiểu biết.

Thêm vào đó, thi thoảng việc được nhắc lại cách cài đặt một phần mềm cũng là điều không thừa.

Dù bạn có thể code trong rất nhiều năm và thậm chí là cả viết sách, blog nhưng khi tiếp xúc với rất nhiều chỉ dẫn cài đặt dự án, bạn vẫn có thể sẽ thấy hết sức bối rối

Một số gợi ý có thể hữu ích cho bạn:

Hãy tự hình dung ra những người với kiến thức nền khác nhau và viết cho họ

Khi những độc giả của bạn có thể vô tình ghé qua và đọc tài liệu của bạn mà không có những kĩ năng và kiến thức giống bạn. Hãy thử viết và review lại, đặt mình vào vị trí của những người đó và suy nghĩ thử xem họ có thể hiểu những gì bạn đang viết hay không. Đọc những gì bạn tự viết nhưng từ nhiều góc nhìn khác nhau.

Thử đọc lại bài viết của bạn sau 1 thời gian bỏ lửng

Đôi khi bạn chỉ cần lùi lại 1 chút, dừng viết khoảng vài giờ hoặc 1 vài ngày sau đó đọc lại những gì mình đã viết trước đó. Có thể thử chuyển sang làm 1 dự án khác, đọc ở một địa điểm khác. Việc thay đổi qua lại này đôi khi có thể khiến cho một số câu chữ mà trước đây bạn thấy rất ổn, bỗng dưng trở nên khó hiểu lạ thường và đó là lúc bạn biết rằng mình cần phải chỉnh sửa lại cách diễn đạt của mình.

Nhờ tới sự giúp đỡ của bạn bè, đồng nghiệp hoặc thậm chí 1 người lạ

Việc có 1 cặp mắt thứ hai đọc và review bài viết của bạn có thể giúp bạn phát hiện ra vấn đề nhanh hơn. Bạn bè có thể giúp bạn nhanh chóng tìm ra những điểm thiếu tự nhiên và thiếu thông tin chỉ dẫn.

Nhưng việc này cũng sẽ hơi phản tác dụng một chút nếu bạn của bạn là một người "tốt" và sợ bạn tổn thương, họ sẽ tỏ ra hữu ích (thực sự thì lại không) bằng cách khen "Tao thấy ổn hết rồi đấy!" hoặc đơn giản chỉ là người bạn đó lại không thể tìm ra điểm nào để đánh giá và góp ý nên bèn bới ra một điểm mà thực sự thì nó cũng không phải là một điều gì to tát.

Nhưng nhìn chung thì việc nhờ người khác giúp đỡ trong việc review thường mang lại kết quả tích cực hơn là tiêu cực.

Sử dụng những từ vựng trung tính (gender-neutral)

Trong những bài viết về khởi nghiệp hay các doanh nhân bạn thường bắt gặp những đại từ nhân xưng chỉ nam giới. Việc này vô hình chung đưa ra một nhận định chung là nữ giới không thể làm được việc này việc kia. Trong lĩnh vực IT mặc dù số lượng nữ giới bị áp đảo nhưng không thể phủ nhận những đóng góp của họ cho ngàng IT nói chung. Vì vậy, dù việc loại bỏ những cụm từ phân biệt giới tính hoàn toàn khỏi những cách diễn đạt là vô cùng khó khăn nhưng không phải là không thể. Bạn chỉ cần bỏ 1 chút thời gian và sự chú tâm để loại bỏ thói quen sử dụng từ này.

Bạn có thể tham khảo bài viết: http://techwhirl.com/gender-neutral-technical-writing/ để tìm hiểu về cách sử dụng những từ ngữ không phân biệt giới tính. Trong bài viết có đưa ra rất nhiều ví dụ cụ thể.

Hãy nhớ những định nghĩa mà bạn cho là hiển nhiên có thể không hề hiển nhiên với người khác

Có những từ ngữ đặc thù của một ngành mà nếu bạn là người mới tìm hiểu thì sẽ thấy rất kì lạ và khó hiểu. Chúng ta càn phải cung cấp đầy đủ những chỉ dẫn thực sự hữu ích, ngắn gọn nhưng vẫn đảm bảo giúp người đọc hiểu được nội dung.

Nếu bạn không muốn hoặc thấy việc hướng dẫn trực tiếp trong bài viết của mình là không phù hợp thì bạn chỉ cần thêm vào đó một đường link tới một nguồn tham khảo phù hợp.

Tài liệu Laravel trên có dẫn nguồn tham khảo tới Composer. Nếu không có link tới Composer, người đọc sẽ nghĩ rằng tác giả mặc định mọi người đọc đều biết về Composer. Nên nếu bạn không biết về nó thì tức là bạn không thể thao tác với project này. Tuy nhiên, chỉ đơn giản bằng cách thêm link vào, tài liệu này đang truyền tải thông tin rằng: "Nếu bạn không biết Composer là gì thì cũng không sao hết, hãy mở đường dẫn này để đọc và tìm hiểu thêm nhé!". Điều này khiến cho tài liệu của họ vừa đầy đủ lại vừa thân thiện với người đọc.

Viết ngắn gọn và sử dụng định dạng căn chỉnh phù hợp

Những đoạn văn dài khủng khiếp và những đoạn văn bản được chia thành từng blocks thật sự rất đáng sợ. Vì nhìn chung mọi người đều không đọc cẩn thận từng chữ ở trên web mà họ sẽ chỉ đọc lướt thôi. Càng nhiều chữ thì sẽ càng khiến người dùng không có hứng thú đọc.

Bạn có thể tối giản nội dung của mình bằng những cách sau:

• Trình bày từ 2-3 câu trong 1 đoạn văn. Không viết cả một khổ dài mà không xuống dòng.
• Nếu bạn không thể thu gọn đoạn văn thì hãy cố chia nó ra thành nhiều gạch đầu dòng, giúp cho việc đọc ý dễ dàng hơn.
• Sử dụng chữ in nghiêng, in đậm để highlight những phần thông tin quan trọng trong bài viết của bạn. Những phần này sẽ thu hút sự chú ý của người đọc và thôi thúc họ đọc toàn bộ nội dung của đoạn văn. Vì khi đó họ đã về cơ bản nắm được đoạn văn đó sẽ nói về nội dung gì.

Hãy xem ví dụ dưới đây:

Đoạn văn phía bên trái có rất nhiều chữ và khó đọc. Bạn có thể đọc nhưng rõ ràng sẽ không dễ đọc nhưng đoạn văn bản phía bên phải.

Bằng cách chia ra làm nhiều gạch đầu dòng, nhiều ý nhỏ, thêm chữ in đậm có chủ đích và làm rõ chủ đề bài viết, bạn cho phép người đọc dễ dàng tiếp thu, nhìn thấy những thông tin quan trọng của đoạn văn bản mà chỉ cần đọc lướt qua.

Sử dụng từ ngữ đơn giản, dễ hiểu

Đừng sử dụng những từ ngữ hoa mỹ thái quá hoặc dùng quá nhiều thành ngữ tục ngữ, cụm từ khó hiểu. Viết càng đơn giản, tường minh càng dễ cho độc giả cũng như dễ dàng cho việc dịch sang những ngôn ngữ khác. Rất có thể sẽ có người đọc bài viết của bạn nhưng bằng cách sử dụng tính năng dịch của Google Chrome. Càng sử dụng ngôn ngữ đơn giản thì những tính năng dịch này lại càng hoạt động chính xác, hiệu quả.

Thêm những hình ảnh chụp màn hình, video và gifs... vào bài viết để minh hoạ cho nội dung bạn truyền tải

Thêm những hình ảnh chụp màn hình và đa phương tiện sẽ rất có ích cho việc minh hoạ những chỉ dẫn, hướng dẫn.

Shopify là một ví dụ cho việc vận dụng rất hiệu quả biện pháp này trong tài liệu của họ. Họ không những thêm vào những ảnh chụp màn hình tương ứng với những chỉ dẫn, mà còn đưa vào những hình ảnh động, để mô tả những quá trình mà họ vừa mô tả bằng lời và hình ảnh tĩnh trước đó nữa.

Khi bạn sử dụng hình ảnh trong bài viết, người đọc sẽ làm dễ dàng liên tưởng và làm theo. Đôi khi ngôn ngữ không thể diễn đạt được hoàn toàn những gì bạn muốn thể hiện và cũng không dễ hiểu bằng 1 hình ảnh. Cũng giống như trong khi giao tiếp hàng ngày, có những thời điểm bạn sẽ thấy sử dụng ngôn ngữ hình thể hoặc 1 hình ảnh minh hoạ nào đó sẽ giúp cho việc truyền đạt của bạn có hiệu quả và nhanh hơn rất nhiều.

Cuối cùng nhưng cũng không kém phần quan trọng. Nếu bạn đang lo lắng về kĩ năng viết lách của bản thân thì bạn cần phải: tập luyện, tập luyện và tập luyện.

Viết càng nhiều càng tốt. Ban đầu có thể sẽ rất chậm nhưng chắc chắn sau đó việc viết lách sẽ trở nên đơn giản hơn nhiều.

Hết sức lưu ý, hãy tối giản bài viết của bạn (cả về độ dài cũng nhưng mức độ khó của nó) và cũng lưu ý rằng độc giả của bạn sẽ có nền tảng cũng như kinh nghiệm khác hoàn toàn so với bạn.

Viết thật nhiều có thể nhưng hãy viết một cách tự nhiên, đừng viết như một cái máy.

Nguồn: https://medium.com/@tracymakes/five-tips-for-improving-your-technical-writing-and-documentation-47353723c8a7