Ghi chú:
- Chương này, cũng như phần còn lại của cuốn sách giáo khoa về viết kỹ thuật này, tập trung vào kỹ năng viết kỹ thuật. Nội dung kỹ thuật ở đây không được đảm bảo sẽ thành công, chính xác hoặc được cập nhật.
- Vui lòng nhấp vào đây để giúp đỡ David McMurrey trả tiền cho dịch vụ lưu trữ web: Quyên góp bất kỳ số tiền nào bạn có thể! Online Technical Writing sẽ vẫn miễn phí.
Trọng tâm của chương này là một trong những ứng dụng quan trọng nhất của viết kỹ thuật—instructions. Như bạn biết, hướng dẫn là những giải thích theo từng bước về cách làm một việc gì đó: cách xây dựng, vận hành, sửa chữa, hoặc bảo trì những thứ.
Hãy nhớ xem qua các ví dụ.
Viết một bộ hướng dẫn cho công việc hoặc cho lớp viết kỹ thuật? Thử cái này Hướng dẫn lập kế hoạch cho các hướng dẫn.
Hướng dẫn viết
Một trong những ứng dụng phổ biến nhất và cũng quan trọng nhất của viết kỹ thuật là hướng dẫn—những giải thích từng bước về cách làm một việc: lắp ráp một thứ gì đó, vận hành một thứ gì đó, sửa chữa một thứ gì đó, hoặc thực hiện bảo dưỡng định kỳ cho một thứ gì đó. Nhưng với một thứ có vẻ dễ và trực quan như vậy, hướng dẫn lại là một trong những tài liệu viết tệ nhất mà bạn có thể tìm thấy. Giống như tôi, có lẽ bạn đã có nhiều trải nghiệm khiến bực bội với những hướng dẫn viết kém. Những gì theo sau trong chương này có thể không phải là một cẩm nang hoàn toàn miễn lỗi để viết hướng dẫn, nhưng nó sẽ chỉ cho bạn những kỹ thuật mà các chuyên gia coi là tốt nhất.
Cuối cùng, việc viết hướng dẫn tốt đòi hỏi:
- Viết rõ ràng, đơn giản
- Một hiểu biết thấu đáo về quy trình trong mọi chi tiết kỹ thuật của nó
- Khả năng đặt mình vào vị trí của người đọc, người đang cố gắng sử dụng hướng dẫn của bạn
- Khả năng của bạn hình dung quy trình một cách rất chi tiết và ghi lại nhận thức đó trên giấy
- Cuối cùng, đó là sự sẵn sàng của bạn để đi xa hơn nữa và kiểm chứng các hướng dẫn của bạn trên đối tượng mà bạn đã viết chúng cho.
Đến lúc này, có lẽ bạn đã nghiên cứu tiêu đề, danh sách và các thông báo đặc biệt—việc viết một bộ hướng dẫn với những công cụ này có lẽ có vẻ hiển nhiên. Chỉ cần tách phần thảo luận thành các danh sách đánh số theo chiều dọc và chèn một vài thông báo đặc biệt vào những điểm rõ ràng là xong! Chà, chưa hẳn vậy, nhưng đó là một khởi đầu tuyệt vời. Chương này khám phá một số đặc điểm của các hướng dẫn có thể khiến chúng phức tạp hơn. Bạn có thể dùng những cân nhắc này để lập kế hoạch cho chính các hướng dẫn của mình.
Infographic do NotebookLM tạo ra của chương này
Một số điều sơ bộ
Khi bắt đầu một dự án viết hướng dẫn, điều quan trọng là xác định cấu trúc hoặc đặc điểm của quy trình cụ thể mà bạn sẽ viết.
Khán giả và tình huống. Ngay từ đầu quá trình, xác định đối tượng và bối cảnh cho hướng dẫn của bạn. Hãy nhớ rằng việc xác định đối tượng nghĩa là xác định mức độ quen thuộc của họ với chủ đề cũng như các chi tiết tương tự khác. Xem phần thảo luận về khán giả và các bước để sử dụng trong việc xác định đối tượng.
Quan trọng nhất, nếu bạn đang học một khóa học viết, bạn sẽ cần viết một mô tả về độc giả của mình và đính kèm nó vào hướng dẫn của bạn. Điều này sẽ cho phép giảng viên đánh giá các hướng dẫn của bạn về mức độ phù hợp với đối tượng độc giả mà bạn hướng tới. Và hãy nhớ rằng trong một khóa học viết kỹ thuật, nên viết cho độc giả không chuyên—điều này sẽ là một thách thức lớn hơn đối với bạn với tư cách là một người viết.
Số nhiệm vụ. Có bao nhiêu nhiệm vụ trong thủ tục mà bạn đang viết? Hãy sử dụng thuật ngữ thủ tục để chỉ toàn bộ tập hợp các hoạt động mà hướng dẫn của bạn dự định thảo luận. Một nhiệm vụ Một nhiệm vụ là một nhóm các hành động bán độc lập trong quy trình: ví dụ, đặt đồng hồ trên lò vi sóng là một nhiệm vụ trong toàn bộ quy trình vận hành lò vi sóng.
Một quy trình đơn giản như thay dầu cho ô tô chỉ có một nhiệm vụ; không có các nhóm hoạt động bán độc lập. Một quy trình phức tạp hơn như sử dụng lò vi sóng chứa nhiều tác vụ bán độc lập như vậy: đặt đồng hồ; đặt mức công suất; sử dụng bộ hẹn giờ; vệ sinh và bảo trì lò vi sóng, trong số những việc khác. (The hướng dẫn sử dụng máy ảnh được tổ chức theo các nhiệm vụ.)
Một số hướng dẫn chỉ có một nhiệm vụ duy nhất, nhưng có nhiều bước trong cùng nhiệm vụ đó. Ví dụ, hãy tưởng tượng một bộ hướng dẫn để lắp đặt một bộ xích đu cho trẻ em. Theo kinh nghiệm của tôi, có hơn 130 bước! Điều đó có thể hơi khiến bạn nản lòng. Một cách tiếp cận tốt là nhóm các bước tương tự và có liên quan thành các pha, và bắt đầu đánh số lại các bước ở mỗi pha mới. Một giai đoạn then là một nhóm các bước tương tự trong một quy trình chỉ thực hiện một nhiệm vụ. Trong ví dụ về bộ xích đu, lắp đặt khung sẽ là một giai đoạn; cố định khung xuống đất sẽ là một giai đoạn khác; lắp ráp xích đu hộp sẽ lại là một giai đoạn nữa.
Sử dụng định hướng nhiệm vụ. Tập trung vào các nhiệm vụ người đọc muốn thực hiện; sử dụng cách diễn đạt 'how to' hoặc '–ing' cho các tiêu đề.
Cách tiếp cận tốt nhất cho cuộc thảo luận theo từng bước. Một điều cần cân nhắc khác, có thể bạn không thể xác định ngay từ đầu, là cách tập trung hướng dẫn của bạn. Đối với hầu hết các hướng dẫn, bạn có thể tập trung vào nhiệm vụ, hoặc bạn có thể tập trung vào công cụ (hoặc tính năng của công cụ).
Trong một cách tiếp cận nhiệm vụ (còn được gọi là định hướng nhiệm vụ) đối với hướng dẫn về cách sử dụng dịch vụ trả lời điện thoại, bạn sẽ có những phần sau:
- ghi âm lời chào của bạn
- phát lại tin nhắn của bạn
- lưu tin nhắn của bạn
- chuyển tiếp tin nhắn của bạn
- xóa tin nhắn của bạn, v.v.
Đây là các tác vụ—những việc điển hình mà chúng ta muốn làm với máy. Để thảo luận thêm, xem chương về phân tích nhiệm vụ.
Mặt khác, trong một cách tiếp cận công cụ đối với hướng dẫn sử dụng máy photocopy, sẽ có những mục không thể ngờ tới sau đây:
- nút sao chép
- nút hủy
- nút phóng to/thu nhỏ
- nút sắp xếp/ghim
- nút sao chép kích thước, v.v.
Nếu bạn thiết kế một bộ hướng dẫn theo kế hoạch này, bạn sẽ viết các bước để sử dụng từng nút hoặc tính năng của máy photocopy. Việc làm cho các hướng dẫn theo cách tiếp cận dựa trên công cụ này hoạt động hiệu quả là khó. Đôi khi, tên của nút không hoàn toàn khớp với nhiệm vụ mà nó liên quan; đôi khi bạn phải dùng nhiều hơn một nút để hoàn thành nhiệm vụ. Tuy nhiên, có những lúc cách tiếp cận công cụ/tính năng có thể được ưa thích.
Nhóm các nhiệm vụ. Liệt kê nhiệm vụ có thể không phải là tất cả những gì bạn cần làm. Có thể có rất nhiều nhiệm vụ đến mức bạn phải nhóm chúng lại để người đọc có thể tìm từng nhiệm vụ dễ dàng hơn. Ví dụ, những nhóm nhiệm vụ sau đây thường gặp trong hướng dẫn:
- các nhiệm vụ mở gói và thiết lập
- cài đặt và tùy chỉnh các tác vụ
- các nhiệm vụ vận hành cơ bản
- các nhiệm vụ bảo trì định kỳ
- các nhiệm vụ khắc phục sự cố; v.v.
Các phần chung trong hướng dẫn
Phần sau đây là một tổng quan về những mục mà bạn thường gặp trong các hướng dẫn. Đừng cho rằng mỗi phần trong số chúng phải phải xuất hiện trong những hướng dẫn thực tế mà bạn viết, cũng không có nghĩa là chúng phải theo thứ tự được trình bày ở đây, cũng không có nghĩa là đây là những phần duy nhất có thể có trong một bộ hướng dẫn.
Khi bạn đọc những nội dung sau về các mục phổ biến trong hướng dẫn, hãy xem qua hướng dẫn ví dụ.
Sơ đồ minh họa các hướng dẫn. Hãy nhớ rằng đây là một mô hình điển hình hoặc phổ biến cho nội dung và tổ chức—vẫn có nhiều cách khác.
Giới thiệu. Lên kế hoạch cho phần mở đầu của hướng dẫn một cách cẩn thận. Hãy đảm bảo nó thực hiện bất kỳ điều nào sau đây (nhưng không nhất thiết theo thứ tự này) nếu áp dụng cho hướng dẫn cụ thể của bạn:
- Chỉ rõ các nhiệm vụ hoặc quy trình cụ thể cần được giải thích cũng như phạm vi bao phủ (cái gì sẽ không được bao phủ).
- Cho biết khán giả cần những kiến thức và nền tảng gì để hiểu các hướng dẫn.
- Hãy đưa ra ý tưởng chung về quy trình và những gì nó đạt được.
- Chỉ ra các điều kiện khi các chỉ dẫn này nên (hoặc không nên) được sử dụng.
- Hãy đưa ra một tổng quan về nội dung của các hướng dẫn.
Xem phần về lời giới thiệu để thảo luận thêm.
Thông báo cảnh báo chung, cảnh báo thận trọng, cảnh báo nguy hiểm. Hướng dẫn thường phải cảnh báo người đọc về khả năng làm hỏng thiết bị của họ, làm sai quy trình và gây tổn hại cho bản thân. Ngoài ra, hướng dẫn thường phải nhấn mạnh những điểm chính hoặc các ngoại lệ. Trong những tình huống này, bạn sử dụng thông báo đặc biệt—ghi chú, cảnh báo, lưu ý và thông báo nguy hiểm. Hãy chú ý cách những thông báo đặc biệt này được sử dụng trong các hướng dẫn ví dụ được liệt kê ở trên.
Nền tảng kỹ thuật hoặc lý thuyết. Vào phần đầu của một số loại hướng dẫn (sau phần giới thiệu, dĩ nhiên), bạn có thể cần một phần thảo luận về kiến thức nền liên quan đến quy trình. Đối với một số hướng dẫn, kiến thức nền này là điều then chốt—nếu không, các bước trong quy trình sẽ chẳng có ý nghĩa. Chẳng hạn, có lẽ bạn đã từng có trải nghiệm với những applet phần mềm mà trong đó bạn xác định màu của riêng mình bằng cách điều chỉnh các thanh trượt đỏ, xanh lục và xanh lam. Để thực sự hiểu bạn đang làm gì, bạn cần có một số kiến thức nền về màu sắc. Tương tự, bạn có thể tưởng tượng rằng, đối với một số hướng dẫn sử dụng máy ảnh, cũng có thể cần đến một chút lý thuyết.
Thiết bị và vật tư. Lưu ý rằng hầu hết các hướng dẫn đều bao gồm một danh sách những thứ bạn cần thu thập trước khi bắt đầu quy trình. Điều này bao gồm thiết bị, các dụng cụ bạn sử dụng trong quy trình (ví dụ như bát trộn, thìa, khuôn bánh mì, búa, máy khoan, và cưa) và vật tư, những thứ được
Thảo luận về các bước. Khi bạn bắt tay vào việc viết từng bước thực tế, có một số điều cần lưu ý: (1) cấu trúc và định dạng của những bước đó, (2) thông tin bổ sung có thể cần thiết, và (3) quan điểm cùng phong cách viết chung.
Cấu trúc và định dạng. Thông thường, chúng ta tưởng tượng một tập hợp các hướng dẫn được định dạng là các danh sách đánh số theo chiều dọc. Và thực tế hầu hết là như vậy. Thông thường, bạn định dạng hướng dẫn từng bước của mình theo cách này. Tuy nhiên, cũng có một số biến thể, cũng như một vài cân nhắc khác:
- Các bước theo thứ tự cố định là các bước phải được thực hiện theo thứ tự đã trình bày. Ví dụ, nếu bạn đang thay dầu trong một chiếc ô tô, xả dầu là một bước mà phải đến trước khi đổ dầu mới. Đây là các danh sách được đánh số (thường là danh sách đánh số theo chiều dọc).
- Các bước có thứ tự thay đổi là những bước có thể được thực hiện gần như theo bất kỳ thứ tự nào. Ví dụ điển hình là những hướng dẫn khắc phục sự cố bảo bạn kiểm tra cái này, kiểm tra cái kia khi bạn đang cố sửa điều gì đó. Bạn có thể thực hiện các bước dạng này gần như theo bất kỳ thứ tự nào. Với loại này, danh sách gạch đầu dòng là định dạng phù hợp.
- Các bước thay thế là những trường hợp trong đó hai hoặc nhiều cách để thực hiện cùng một việc được trình bày. Các bước thay thế cũng được sử dụng khi có thể tồn tại các điều kiện khác nhau. Sử dụng danh sách gạch đầu dòng cho loại này, với OR chèn giữa các lựa chọn, hoặc phần mở đầu cho biết rằng các phương án thay thế sắp được trình bày.
- Các bước lồng nhau. Trong một số trường hợp, các bước riêng lẻ trong một quy trình tự thân có thể khá phức tạp và cần được chia nhỏ thành các bước con. Trong trường hợp này, bạn thụt lề thêm và đánh số các bước con là a, b, c, và cứ như vậy.
- "Stepless" hướng dẫn. Và cuối cùng có những hướng dẫn thực sự không thể dùng danh sách dọc có đánh số và hầu như không (nếu có thì rất ít) hướng dẫn người đọc theo phong cách chỉ dẫn trực tiếp. Một số tình huống phải được khái quát hóa hoặc biến đổi đến mức các bước không thể được nêu ra.
Xem chương về các danh sách cho phong cách và định dạng của các khả năng này.
Thảo luận bổ sung. Thường thì chỉ đơn giản bảo độc giả làm việc này hay làm việc kia là chưa đủ. Họ cần thêm thông tin giải thích như cách mà thứ đó nên trông ra sao trước và sau bước; tại sao họ nên quan tâm đến việc thực hiện bước này; nguyên lý cơ học nào đứng sau những gì họ đang làm; thậm chí là giải thích ở mức vi mô hơn về bước—thảo luận về các hành động cụ thể tạo nên bước.
Vấn đề với phần thảo luận bổ sung, tuy nhiên, là nó có thể che khuất bước thực tế. Bạn muốn bước thực tế—những hành động cụ thể mà người đọc phải thực hiện—nổi bật. Bạn không muốn tất cả bị vùi trong một đống chữ. Có ít nhất hai kỹ thuật để tránh vấn đề này: bạn có thể tách phần hướng dẫn ra khỏi phần bổ sung thành các đoạn riêng biệt; hoặc bạn có thể in đậm phần hướng dẫn.
Làm đậm các bước thực tế của người dùng trong hướng dẫn. Văn bản in đậm giúp phân biệt hành động thực tế với thông tin bổ sung.
Tránh viết kiểu điện báo—lược bỏ các mạo từ "được hiểu" (the, a, an). Đúng là robot viết như vậy, nhưng chúng ta không cần làm như thế.)
Phong cách viết.
Một trong những vấn đề điển hình về phong cách viết trong hướng dẫn là mọi người dường như muốn bỏ các mạo từ: "Nhấn nút Tạm dừng trên bảng điều khiển phía trước để tạm thời dừng hiển thị thông tin" hoặc "Người Trái Đất, xin vui lòng cung cấp địa chỉ nhà hàng pizza gần nhất." Tại sao chúng ta làm điều này? Có phải tất cả chúng ta đều thầm muốn trở thành robot không? Dù sao, hãy chắc chắn bao gồm tất cả các mạo từ (một, một, cái) và những từ tương tự khác mà chúng ta thường dùng trong hướng dẫn.
Đồ họa trong Hướng dẫn
Có lẽ còn hơn bất kỳ hình thức văn bản nào khác (trừ có lẽ là truyện tranh), đồ họa rất quan trọng trong các hướng dẫn. Đôi khi, từ ngữ đơn giản không thể giải thích được bước đó. Minh họa thường rất quan trọng để người đọc có thể hình dung những gì họ cần làm.
Trong một khóa học viết kỹ thuật, các hướng dẫn có thể yêu cầu bạn bao gồm các minh họa hoặc các loại đồ họa—bất cứ thứ gì thường được sử dụng trong các hướng dẫn. Vấn đề, tất nhiên, có thể là bạn không có sẵn những đồ họa phù hợp cho các hướng dẫn cụ thể của mình, và bạn không cảm thấy quá tự tin về năng khiếu nghệ thuật của mình. Có những cách để vượt qua những vấn đề này! Hãy xem các gợi ý trong đồ họa. Trong chương đó, bạn sẽ thấy không chỉ những gợi ý về cách tạo đồ họa, mà còn cả các yêu cầu về định dạng của chúng.
Định dạng trong Hướng dẫn
Các tiêu đề. Trong hướng dẫn của bạn, hãy tận dụng tốt các tiêu đề. Thông thường, bạn sẽ muốn có tiêu đề cho bất kỳ phần bối cảnh nào bạn có, phần thiết bị và vật tư, một tiêu đề chung cho phần hướng dẫn thực tế, và các tiêu đề phụ cho từng nhiệm vụ hoặc giai đoạn riêng lẻ trong phần đó. Hãy xem các ví dụ ở phần đầu của chương này. Xem tiêu đề cho các yêu cầu chung.
Danh sách. Tương tự, các hướng dẫn thường sử dụng nhiều danh sách, đặc biệt là các danh sách dọc được đánh số cho phần giải thích từng bước thực tế. Các danh sách dọc đơn giản hoặc danh sách hai cột thường phù hợp cho phần thiết bị và vật tư. Danh sách trong câu phù hợp khi bạn đưa ra tổng quan về những điều sắp tới. Xem các danh sách cho các yêu cầu chung.
Thông báo đặc biệt. Trong hướng dẫn, bạn phải cảnh báo người đọc về các khả năng mà họ có thể làm hỏng thiết bị của mình, lãng phí vật tư, khiến toàn bộ quy trình thất bại, làm bị thương bản thân hoặc người khác—thậm chí nghiêm trọng hoặc tử vong. Các công ty đã bị kiện vì thiếu những thông báo đặc biệt này, vì thông báo đặc biệt được viết kém, hoặc vì thông báo đặc biệt được đặt sai chỗ. Xem thông báo đặc biệt để có một thảo luận đầy đủ về cách sử dụng đúng các thông báo đặc biệt này cũng như về định dạng và vị trí của chúng trong các hướng dẫn.
Số, chữ viết tắt, và ký hiệu. Hướng dẫn cũng sử dụng nhiều số, viết tắt và ký hiệu. Cho hướng dẫn trên những lĩnh vực này.
Thụt lề của các thông báo trong hướng dẫn. Trong ví dụ đầu tiên, hãy chú ý cách thông báo được thụt lề tới văn bản của bước trước. Trong ví dụ thứ hai, lưu ý rằng thông báo nghiêm trọng được đặt ở đầu trước bất kỳ bước nào.
Lời nhắc AI cho hướng dẫn
Danh sách kiểm tra, vốn thường không được đọc, có thể được dùng làm nguồn cho các lời nhắc AI sau khi chỉnh sửa một chút. Sao chép phần sau, dán nó vào một hệ thống AI như Gemini của Google, và xem bạn có thể đã bỏ sót điều gì.
Lưu ý: Tất cả các tham chiếu đến nội dung, định dạng, phong cách của thư xin việc hoặc các thành phần của chúng có thể được tìm thấy trong sách giáo khoa trực tuyến về viết kỹ thuật.
Khi bạn muốn sử dụng AI để đánh giá một dự án viết, hãy giới thiệu bản thân, nói với AI bạn là ai, bạn muốn gì. Cung cấp cho AI một điểm tham chiếu để thực hiện việc đánh giá, chẳng hạn như một sách giáo khoa trực tuyến. Sau đó đăng những gì bạn muốn AI kiểm tra trong phần đánh giá của nó.
Sửa phần giới thiệu để phù hợp với bản sắc của bạn.
|
Hướng dẫn Lời nhắc AI Xin chào, AI. Tôi yêu cầu bạn đánh giá các hướng dẫn do một sinh viên năm hai đại học Mỹ viết. Dưới đây là tóm tắt các chương sách giáo khoa về hướng dẫn và thông báo để sử dụng làm cơ sở cho việc đánh giá của bạn. (Thông tin nhận dạng đã được che):
|
Thông tin liên quan
Làm thế nào tôi có thể tạo các hướng dẫn sử dụng hiệu quả
chi phí ẩn của việc quá trực quan đến mức không cần hướng dẫn sử dụng
Các sổ tay vận hành có góp phần vào hiệu quả kinh doanh không?
Tôi rất mong nhận được suy nghĩ, phản ứng, và những lời phê bình của bạn về chương này: phản hồi của bạn—David McMurrey.
