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)

Computer graphics is an incredibly interesting field. There are many rules, exceptions to those rules, and interesting details. However, expanding into details can add unnecessary content; therefore, keep the text concise and relevant to the end user.

Bảo Quản Dễ Dàng (Maintainable)

Keep in mind that Blender has frequent releases, so try to write content that will not have to be redone the moment some small change is made. This also helps a small documentation community maintain the manual.

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" để ý.

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

  • 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.

  • Keep sentences short and clear.

  • Đ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:

  • Avoid writing in the first person perspective, about yourself, or about your own opinions.

  • 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)"

    These details are not useful for users and become quickly outdated.

  • Tránh việc viết về các lỗi lầm trong phần mềm.

    Blender often has hundreds of bugs fixed between releases, so the manual cannot be expected to keep up.

    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.

  • Avoid product placements, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

  • 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).

  • Avoid listing every option in a menu, such as frame rates.

    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
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have 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 line interpolated between Control Vertices.
   Common types include Bézier and NURBS.