Hướng Dẫn về Phong Cách Viết -- Writing Style Guide¶

Mục Đích Chủ Yếu -- Primary Goals¶

The main goals for this manual are as follows:

Hướng Trọng Tâm vào Người Dùng -- User Focused: The manual is written for people educated in computer graphics, who understand the basics of 3D and/or know other 3D software. While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users.
Hoàn Thành -- Complete: The manual provides detailed functional description of all features, tools and options in Blender. While there is a canonical source of truth for each of Blender's key areas, this does not mean we have to document every small detail. The manual should provide information on what a feature is, how to use it, and its purpose. More background information should be provided when necessary to give deeper understanding of a 3D pipeline.
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, ngoại lệ đối với các quy tắc và các chi tiết hứng khởi. Việc đào sâu vào các chi tiết có thể dẫn đến việc cho thêm các nội dung không cần thiết, cho nên, hãy cố gắng giữ cho văn bản ngắn gọn và có thích hợp với chủ đề đang xử lý.
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 -- strongly để ý.
Sử dụng tiếng Anh Mỹ (ví dụ sự khác biệt về cách đánh vần: modeling (mô hình hóa) chứ không dùng modelling (hai chữ l), và dùng color (màu sắc) chứ không dùng colour (có thêm chữ 'u')), đồng thời, định dạng hình thức của 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 chấm).
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 đề.
Nhớ 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 là một điều tốt.
Nếu bạn không chắc chắn về sự hoạt động của một tính năng 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ọ.

Tránh:

Tránh viết trong ngôi thứ nhất (chẳng hạn dùng chữ 'tôi') 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 loại 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ó chừng 100 lỗi được chỉnh sửa, vì vậy, đề 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 đề được các nhà phát triển biết đến, song, không được giải quyết trước khi bản phát hành tiếp theo, có thể được ghi thành Những Hạn Chế Từng Biết Đến -- Known Limitations. Trong một số trường hợp, tốt nhất nên đưa chúng vào phần xử lý sự cố -- troubleshooting.
Tránh việc đề cập đến các sản phẩm, tức là quảng bá phần mềm hoặc thương hiệu phần cứng không cần thiết. Cố gắng giữ góc nhìn khách quan, trung lập đối với các nhà cung cấp sản phẩm, nếu có thể.
Tránh việc đi sâu và giải thích một cách 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ó cách giải thích đơn giản hơn.

(E.g. explaining how mesh smoothing algorithms work is unnecessary, but the blending types of a Mix node do need a mathematical explanation.)
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 thuật ngữ nói chung, 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 giản là bỏ qua. -- Những danh sách như vậy chỉ hiển thị những gì vốn dĩ đã hiển nhiên -- obvious trong giao diện mà thôi và để 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 trong Blender giữa các bản phát hành, bản thông báo về phát hành đã được sử dụng cho mục đích nà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ị một giá trị nào đó đã được đo lường, song tối nghĩa và bất định, chúng ta không cần phải đề cập đến nó.
Đừng chỉ đơn giản sao chép các chú giải công cụ từ Blender. -- Mọi người cần phải tìm đến bản hướng dẫn sử dụng để tìm hiểu nhiều/lớn hơn -- more, 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 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 soạn thảo khác):
```
.. TODO, how does this tool work? ask Joe Blogg's.
```

Bảng Thuật Ngữ -- Glossary¶

Phần này sẽ đặc chuyên về Bảng Thuật Ngữ -- Glossary, tức là bản 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.
Tránh sử dụng các cấu trúc như "nó là -- it is" hoặc "xyz là -- xyz is" 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.
Tránh việc kéo dài các mục 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ỉ nên liên kết đến phần đó mà thôi, và nên tuyệt đối tránh việc tự 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.
```

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.

Thay vào đó, sẽ nên đượ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.

Sẽ được viết như thế này 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.

Sẽ được viết giống như thế này hơn, tránh việc sử dụng "nó là -- it is":

Curve
   A type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.