Hướng Dẫn về Phong Cách Viết (Writing Style Guide)
Mục Đích Chủ Yếu (Primary Goals)
Mục tiêu chính của bản hướng dẫn sử dụng này là như sau:
- Hướng Trọng Tâm vào Người Dùng (User Focused)
Hướng dẫn sử dụng được viết cho những người đã được giáo dục về đồ họa máy tính, những người Hiểu biết những điều cơ bản của 3D và/hoặc biết một phần mềm 3D nào khác. Tuy một số lĩnh vực đồ họa máy tính có tính kỹ thuật cao, song hướng dẫn này sẽ hướng trọng tâm vào những người dùng bình thường, không Hiểu biết kỹ thuật, dễ Hiểu.
- Hoàn Thành (Complete)
Hướng dẫn sử dụng cung cấp miêu tả chức năng chi tiết về toàn bộ các tính năng, công cụ và các tùy chọn trong Blender. Mặc dù mỗi lĩnh vực căn bản của Blender đều có một chân lý riêng mà mọi người phải tuân thủ theo, song nó không có nghĩa là chúng tôi phải giải thích từng chi tiết nhỏ một. Hướng dẫn sử dụng nên cung cấp thông tin về một tính năng và giải thích nó là gì, cách sử dụng và mục đích của nó. Bản hướng dẫn sử dụng cũng nên cung cấp thêm thông tin nền tảng cơ bản, khi cần thiết, để cho người đọc Hiểu sâu hơn về quy trình 3D.
- Ngắn Gọn (Concise)
Đồ họa máy tính là một lĩnh vực vô cùng thú vị, có rất nhiều quy tắc trong đó, và cả những điều được phép làm song nằm ngoài quy tắc, cùng các chi tiết hứng khởi khác nữa. Song việc đào sâu vào các chi tiết cũng có thể dẫn đến việc cho thêm những nội dung không cần thiết vào bản tài liệu, cho nên, xin hãy cố gắng giữ cho văn bản ngắn gọn và thích hợp với chủ đề đang xử lý mà thôi.
- Bảo Quản Dễ Dàng (Maintainable)
Hãy nhớ rằng Blender sẽ phát hành các phiên bản khá thường xuyên, vì vậy hãy cố gắng viết làm sao cho nội dung không phải làm lại từ thời điểm những thay đổi nhỏ được thực hiện. Điều này cũng giúp cho cộng đồng nhỏ quản lý bản tài liệu duy trì bản hướng dẫn sử dụng dễ dàng.
Hướng Dẫn về Nội Dung (Content Guidelines)
Để duy trì phong cách viết nhất quán trong bản hướng dẫn sử dụng, xin vui lòng ghi nhớ hướng dẫn trong trang này và chỉ làm khác đi khi bạn có lý do chính đáng để làm như vậy.
Quy Luật Thông Thường:
Kiểm tra chính tả là điều phải "hết sức" để ý.
Sử dụng Tiếng Anh Giọng Mỹ (ví dụ sự khác biệt về cách đánh vần: modeling chứ không dùng modelling, và dùng color chứ không dùng colour, đồng thời, hình thức viết các con số (chẳng hạn: 2,718.28 mà không dùng 2 718.28, dùng dấu phẩy để tách phân phần nghìn chứ không dùng dấu cách trống, dấu chấm để tách phân phần thập phân, chứ không dùng Dấu Phẩy).
Hãy quan tâm đến ngữ pháp, dùng từ ngữ thích hợp và sử dụng tiếng Anh đơn giản.
Giữ cho các câu ngắn gọn và rõ ràng, dẫn đến văn bản sẽ dễ đọc, khách quan và sát vào vấn đề.
Điều nên làm là nên cho biết lý do tại sao, hoặc làm thế nào, để một tùy chọn trở nên hữu ích cho người dùng.
Nếu bạn không chắc chắn về hoạt động của một tính năng nào đó thì xin hãy hỏi người khác, hoặc lùng tìm người đã phát triển tính năng và hỏi họ xem.
Tránh:
Tránh viết trong ngôi thứ nhất trong cuộc hội thoại, hoặc viết về bản thân, hoặc viết ý kiến của riêng mình.
Tránh các lời nói lấp lửng (weasel words) và tạo cảm giác mơ hồ không cần thiết, ví dụ:
"Tái nạp tập tin có thể sẽ sửa được lỗi lầm""Đại đa số người dùng không sử dụng tùy chọn này, bởi vì ..."Tránh bao gồm các chi tiết cụ thể như:
"Blender có 23 bộ điều chỉnh khác nhau.""Việc bật tính năng duyệt thảo sẽ làm tăng thêm 65536 bytes vào kích cỡ của mỗi tập tin blend (trừ phi nó được nén lại)"Những chi tiết này không hữu ích cho người dùng ghi nhớ và chúng sẽ nhanh chóng trở nên lỗi thời.
Tránh việc viết về các lỗi lầm trong phần mềm.
Giữa hai bản phát hành, Blender thường sẽ có hằng 100 lỗi được biên soạn, vì vậy, việc đề cập đến nó trong bản hướng dẫn sử dụng không phải là một điều sát thực trong khi duy trì tính cập nhật của bản hướng dẫn sử dụng.
Các vấn đề lỗi lầm trong phần mềm mà các nhà phát triển biết đến, và rất có khả năng là chúng sẽ không được giải quyết trước khi bản phát hành tiếp theo xuất xưởng, có thể phải được ghi lại trong phần "Những Hạn Chế Từng Biết Đến". Trong một số trường hợp, tốt nhất là đưa chúng vào phần xử lý sự cố (troubleshooting) thì hơn.
Tránh việc đề cập đến các sản phẩm, tức quảng bá phần mềm hoặc thương hiệu phần cứng một cách không cần thiết. Cố gắng giữ góc nhìn khách quan, trung lập đối với nhà cung cấp nội dung, nếu có thể.
Tránh việc đi sâu và giải thích một phương pháp máy móc về phương pháp thực hiện toán học/thuật toán một tính năng nào đó trong khi có phương pháp giải thích đơn giản hơn.
(ví dụ: giải thích phương pháp các thuật toán làm mịn khung lưới như thế nào là một việc không cần thiết, song các kiểu kết hợp của một nút Hòa Trộn thì cần có sự giải thích một cách toán học.)
Tránh việc lặp đi, lặp lại các phần của văn bản. Chúng ta chỉ cần đơn giản giải thích nó một lần, rồi từ đó trở đi, tham chiếu đến phần giải thích đó là đủ.
Đối với các thuật ngữ nói chung, xin hãy định nghĩa các
:term:(từ chuyên môn) trong bảng thuật ngữ (glossary).Tránh liệt kê các tùy chọn tương tự, chẳng hạn như liệt kê mọi giá trị đặt trước, hoặc mọi tốc độ khung hình, trong một trình đơn đã chọn nào đó.
Nội dung của chúng có thể được tóm tắt lại, hoặc đơn thuần bỏ qua. -- Những danh sách như vậy chỉ hiển thị những gì vốn dĩ đã "hiển nhiên" trong giao diện mà thôi, song nếu ghi lại thì chúng sẽ để lại một lượng lớn văn bản cần phải đọc và bảo quản.
Tránh việc ghi lại những thay đổi giữa các bản phát hành, các bản ghi chú phát hành là cái để làm việc ấy. Chúng ta chỉ cần ghi lại trạng thái hiện tại của Blender mà thôi.
Trừ khi đơn vị của một giá trị nào đó đã được đo lường rồi, song tối nghĩa và bất định thì chúng ta phải nhắc đến, còn không thì chúng ta không cần phải đề cập đến nó nữa.
Đừng chỉ đơn thuần sao chép các chú thích công cụ từ Blender mà thôi. -- Người ta sẽ tự tìm đến bản hướng dẫn sử dụng để tìm hiểu "tăng", thay vì những gì đã được cung cấp trên Giao Diện Người Dùng.
Việc cho thêm nhận xét vào sẽ chỉ nên sử dụng là phương sách cuối cùng mà thôi (cái này không được hiển thị trong trang HTML, song có lợi cho các trình biên soạn khác):
.. TODO, how does this tool work? ask Joe Blogg's.
Glossary (Bảng Thuật Ngữ)
Phần này sẽ đặc chuyên về Bảng Thuật Ngữ (Glossary), tức là bản mà trong đó chúng ta định nghĩa các từ chuyên môn thông dụng trong Blender và trong đồ họa máy tính.
Quy Luật Thông Thường:
Định nghĩa thuật ngữ trước khi cung cấp thêm bất kỳ thông tin nào khác.
Tránh sử dụng các cấu trúc như "nó là" hoặc "xyz là" trước định nghĩa.
Tránh việc lặp lại thuật ngữ ngay lập tức, hoặc sử dụng chính từ đó trong định nghĩa.
Tránh việc cho thêm các thuật ngữ không có trong giao diện của Blender, hoặc trong bản hướng dẫn sử dụng, vào.
Tránh các mục kéo dài quá mức. Nếu việc giải thích một thuật ngữ phức tạp là cần thiết thì hãy bổ sung bằng các liên kết ra các nguồn ở bên ngoài.
Tránh việc sao chép tài liệu; Nếu việc giải thích cụm từ này là trọng tâm chính của một phần khác trong bản hướng dẫn sử dụng (ví dụ: nếu cụm từ là tên của một công cụ) thì bạn chỉ cần liên kết đến phần đó mà thôi, và nên tránh việc tạo ra một chú giải thuật ngữ.
Tham chiếu URL phải được cho thêm ở phần cuối, với định dạng như sau đây, ví dụ,:
See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.
Một Số Ví Dụ (Examples)
Mục này:
Displacement Mapping
Uses a grayscale heightmap, like Bump Mapping,
but the image is used to physically move the vertices of the mesh at render time.
This is of course only useful if the mesh has large amounts of vertices.
Đáng ra phải được viết như thế này, đặt định nghĩa trước:
Displacement Mapping
A method for distorting vertices based on an image.
Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
This relies on the mesh having enough geometry.
Mục này:
Doppler Effect
The Doppler effect is the change in pitch that occurs
when a sound has a velocity relative to the listener.
Nên phải được viết như thế này thì hơn, tránh sự lặp lại thuật ngữ ngay lập tức:
Doppler Effect
Perceived change in pitch that occurs
when the source of a sound is moving relative to the listener.
Mục này:
Curve
It is a class of objects.
In Blender there are Bézier curves and NURBS curves.
Đáng ra phải được viết như thế này thì hơn, tránh việc sử dụng "nó là":
Curve
A type of object defined in terms of a line interpolated between Control Vertices.
Available types of curves include Bézier and NURBS.