Vui lòng nhấp vào đây để giúp đỡ David McMurrey trả tiền cho dịch vụ lưu trữ web:
Hãy ủng hộ bất kỳ số tiền nhỏ nào bạn có thể!
Viết kỹ thuật trực tuyến sẽ vẫn miễn phí.

Tài liệu kỹ thuật (bao gồm sổ tay, tài liệu trắng và hướng dẫn) có nhiều thiết kế khác nhau tùy thuộc vào ngành, nghề hoặc tổ chức. Chương này giới thiệu một thiết kế truyền thống. Nếu bạn đang tham gia một khóa học viết kỹ thuật, hãy chắc chắn rằng thiết kế được trình bày trong chương này là chấp nhận được. Điều này cũng đúng nếu bạn đang viết một tài liệu kỹ thuật trong bối cảnh khoa học, kinh doanh hoặc chính phủ.

NotebookLM-generated infographic of this chapter Infographic được tạo ra bởi NotebookLM của chương này

Lưu ý: Trong nhiều năm, cuốn sách giáo khoa viết kỹ thuật trực tuyến này đã gọi chung các báo cáo là gần như bất kỳ thứ gì chứa thông tin kỹ thuật. Nhưng vì "báo cáo" đề cập đến một thể loại tài liệu kỹ thuật cụ thể, nên cần phải thay đổi sang thuật ngữ chung "techdoc", viết tắt cho tài liệu kỹ thuật.

Tài liệu kỹ thuật (tên chung cho các tài liệu kỹ thuật) có các thông số kỹ thuật giống như bất kỳ loại dự án nào khác. Thông số kỹ thuật cho tài liệu kỹ thuật liên quan đến bố cục, tổ chức và nội dung, định dạng của tiêu đề và danh sách, thiết kế của đồ họa, và những điều tương tự. Lợi thế của một cấu trúc và định dạng yêu cầu cho tài liệu kỹ thuật là bạn hoặc bất kỳ ai khác có thể mong đợi chúng được thiết kế theo cách quen thuộc—bạn biết điều gì cần tìm và nơi nào để tìm kiếm nó. Tài liệu kỹ thuật thường được đọc vội vàng—mọi người đang vội vàng để đến với thông tin họ cần, những sự thật chính, những kết luận, và các yếu tố cần thiết khác. Một định dạng tài liệu kỹ thuật tiêu chuẩn giống như một khu phố quen thuộc.

Khi bạn phân tích thiết kế của một tài liệu kỹ thuật, hãy chú ý đến việc một số phần lặp lại. Việc sao chép này liên quan đến cách mọi người đọc tài liệu kỹ thuật. Họ không đọc tài liệu kỹ thuật theo thứ tự: họ có thể bắt đầu với bản tóm tắt điều hành, lướt qua và có thể không đọc mọi trang. Thử thách của bạn là thiết kế tài liệu kỹ thuật sao cho những người đọc này gặp được những thông tin và kết luận chính, bất kể họ đọc bao nhiêu phần của tài liệu kỹ thuật hoặc theo thứ tự nào.

Hãy chắc chắn xem cái này ví dụ tài liệu kỹ thuật.

Các thành phần tiêu chuẩn của một báo cáo kỹ thuật điển hình sẽ được thảo luận trong chương này. Các phần tiếp theo hướng dẫn bạn qua từng thành phần, chỉ ra những đặc điểm chính. Khi bạn đọc và sử dụng những hướng dẫn này, hãy nhớ rằng đây chỉ là hướng dẫn, không phải là quy tắc bất di bất dịch. Các công ty, nghề nghiệp và tổ chức khác nhau có những hướng dẫn đa dạng cho tài liệu kỹ thuật, bạn sẽ cần điều chỉnh thực hành của mình theo những hướng dẫn đó cũng như những hướng dẫn được trình bày ở đây.

Thông điệp Gửi đi

Tin nhắn gửi kèm là một bức thư đính kèm (hoặc ghi chú) hoặc một email. Bức thư (hoặc ghi chú) vật lý được gắn vào bên ngoài hồ sơ kỹ thuật bằng một cái kẹp giấy hoặc được đóng bên trong hồ sơ. Email chứa liên kết đến hồ sơ kỹ thuật hoặc hồ sơ được đính kèm. Đây là một thông điệp từ bạn—người viết hồ sơ kỹ thuật—đến người nhận, người đã yêu cầu hồ sơ kỹ thuật và có thể còn trả tiền cho bạn vì sự tư vấn chuyên môn của bạn. Về bản chất, nó nói: "Được rồi, đây là hồ sơ kỹ thuật mà chúng ta đã thỏa thuận tôi sẽ hoàn thành vào ngày này. Tóm lại, nó chứa cái này và cái kia, nhưng không đề cập đến cái này hoặc cái kia. Hãy cho tôi biết nếu nó đáp ứng nhu cầu của bạn." Tin nhắn gửi kèm giải thích bối cảnh—các sự kiện dẫn đến việc tạo ra hồ sơ kỹ thuật. Nó chứa thông tin về hồ sơ kỹ thuật mà không thuộc về hồ sơ kỹ thuật.

Business letter and email versions of transmital message
Ví dụ về thư chuyển giao và thông điệp chuyển giao.

Trong ví dụ về thư chuyển giao, hãy lưu ý định dạng thư kinh doanh tiêu chuẩn. Nếu bạn viết một tài liệu kỹ thuật nội bộ, hãy sử dụng định dạng công văn thay vào đó; trong cả hai trường hợp, nội dung và tổ chức đều giống nhau:

Đoạn đầu tiên. Trích dẫn tên của tài liệu kỹ thuật, để nghiêng nó. Nó cũng đề cập đến ngày ký kết thỏa thuận để viết tài liệu kỹ thuật.

Đoạn giữa. Tập trung vào mục đích của tài liệu kỹ thuật và cung cấp cái nhìn tổng quan ngắn gọn về nội dung của tài liệu kỹ thuật.

Đoạn cuối cùng. Khuyến khích độc giả liên hệ nếu có câu hỏi, nhận xét hoặc lo ngại. Kết thúc với một cử chỉ thiện chí, bày tỏ hy vọng rằng độc giả thấy tài liệu kỹ thuật này đạt yêu cầu.

Giống như bất kỳ phần tử nào khác trong tài liệu kỹ thuật, bạn có thể cần phải điều chỉnh nội dung của thông điệp (hoặc ghi chú) này cho các tình huống cụ thể. Ví dụ, bạn có thể muốn thêm một đoạn khác, liệt kê các câu hỏi mà bạn muốn độc giả xem xét khi họ xem tài liệu kỹ thuật.

Bìa, Trang tiêu đề và Nhãn

Nếu tài liệu kỹ thuật của bạn dài hơn mười trang, hãy bìa nó bằng một cách nào đó và tạo một nhãn cho bìa.

Bìa

Bìa mang lại cho tài liệu kỹ thuật một vẻ ngoài chuyên nghiệp và bảo vệ. Bạn có thể chọn từ nhiều loại bìa khác nhau. Hãy ghi nhớ những mẹo này:

Thông thường, những cuốn sổ có giấy rời, hoặc bìa kẹp là ít được ưa chuộng hơn. Chúng quá nặng nề cho các tài liệu kỹ thuật ngắn, và lỗ trang có xu hướng bị rách. Tất nhiên, bìa kẹp giúp việc thay đổi trang trở nên dễ dàng; nếu đó là cách tài liệu kỹ thuật của bạn sẽ được sử dụng, thì đó là một lựa chọn tốt. Ở "phân khúc cao cấp" là những bìa quá cầu kỳ với vẻ ngoài giả da và viền màu vàng. Tránh xa chúng—giữ cho nó đơn giản, dễ hiểu và chức năng.

Trang tiêu đề

Đơn giản nhất, tiêu đề tài liệu kỹ thuật là một bản sao của những gì trên bìa trước — có thể với vài chi tiết bổ sung.

Hãy xem trang tiêu đề. Tóm tắt và Tóm tắt điều hành.

Nhãn hiệu

Hãy chắc chắn xây dựng một nhãn cho bìa tài liệu kỹ thuật của bạn. Đây là một bước mà một số nhà viết tài liệu kỹ thuật quên. Nếu không có nhãn, tài liệu kỹ thuật sẽ trở nên vô danh; nó sẽ bị bỏ qua.

Cách tốt nhất để tạo nhãn là sử dụng phần mềm xử lý văn bản của bạn để thiết kế nó trên một trang chuẩn với một hộp đồ họa xung quanh thông tin nhãn. In ra, sau đó đi đến cửa hàng photo và để nó được photocopy trực tiếp lên bìa tài liệu kỹ thuật.

Không có nhiều thông tin trên nhãn: tiêu đề tài liệu kỹ thuật, tên của bạn, tên tổ chức của bạn, số theo dõi tài liệu kỹ thuật và một ngày. Không có yêu cầu tiêu chuẩn cho nhãn, mặc dù công ty hoặc tổ chức của bạn nên có các yêu cầu riêng. (Một ví dụ về nhãn tài liệu kỹ thuật được hiển thị bên dưới.)


Thư chuyển giao và bìa tài liệu kỹ thuật (có nhãn bìa).

Tóm tắt và Tóm tắt điều hành

Hầu hết các tài liệu kỹ thuật chứa ít nhất một bản tóm tắt—đôi khi có hai, trong trường hợp đó, các bản tóm tắt đóng các vai trò khác nhau. Các bản tóm tắt tóm lược nội dung của tài liệu kỹ thuật, nhưng các loại khác nhau thực hiện điều này theo những cách khác nhau:

Nếu bản tóm tắt điều hành, phần giới thiệu và thông điệp chuyển giao khiến bạn cảm thấy lặp lại, hãy nhớ rằng độc giả không nhất thiết bắt đầu từ đầu một tài liệu công nghệ và đọc từ trang này đến trang khác cho đến khi kết thúc. Họ sẽ lướt qua: họ có thể xem qua bảng mục lục; họ thường lướt qua tóm tắt điều hành để tìm các thông tin và kết luận quan trọng. Họ có thể chỉ đọc cẩn thận một hoặc hai phần trong nội dung tài liệu công nghệ, và sau đó bỏ qua phần còn lại. Vì những lý do này, tài liệu công nghệ được thiết kế với một số sự trùng lặp để độc giả có thể chắc chắn thấy được thông tin quan trọng bất kể họ bắt đầu từ đâu trong tài liệu công nghệ.


Mục lục (cái nào đến trước) sau đó là tóm tắt điều hành.

Mục Lục

Bất kỳ định dạng mục lục (TOC) nào bạn sử dụng, đây là những tiêu chuẩn phổ biến: