Nguyên tắc nội dung¶

Mặc dù chúng tôi khuyến khích bạn áp dụng phong cách viết riêng của mình, một số quy tắc vẫn được áp dụng để duy trì sự rõ ràng và đảm bảo người đọc có thể dễ dàng hiểu nội dung.

Quan trọng

Chúng tôi đặc biệt khuyến nghị bạn đọc trang Hướng dẫn và bảng tra cứu nhanh RST và trang chính Tài liệu trước khi đóng góp.

Tổ chức tài liệu¶

Khi viết tài liệu về một chủ đề nhất định, hãy giữ các trang trong cùng một thư mục được sắp xếp gọn gàng.

Đối với hầu hết các chủ đề, một trang duy nhất là đủ. Đặt trang đó vào phần phù hợp của tài liệu (ví dụ: nội dung liên quan đến ứng dụng CRM sẽ nằm dưới User Docs ‣ Sales ‣ CRM) và tuân theo nguyên tắc về cấu trúc tài liệu.

Đối với các chủ đề phức tạp hơn, có thể cần nhiều trang để bao quát hết mọi khía cạnh. Thông thường, bạn sẽ thấy mình đang thêm tài liệu vào một chủ đề đã được đề cập một phần. Trong trường hợp đó, bạn có thể tạo một trang mới và đặt nó cùng cấp với các trang liên quan khác, hoặc thêm các phần mới vào một trang hiện có. Khi viết tài liệu cho một chủ đề phức tạp từ đầu, hãy tổ chức nội dung trên nhiều trang con được tham chiếu từ trang cha của thư mục đó (trang TOC); bất cứ khi nào có thể, hãy viết nội dung trên trang cha thay vì chỉ trên các trang con. Làm cho trang cha có thể truy cập được từ menu điều hướng bằng cách sử dụng directive metadata show-content.

Ghi chú

Tránh trùng lặp nội dung bất cứ khi nào có thể; nếu một chủ đề đã được viết tài liệu ở trang khác, hãy tham chiếu đến thông tin hiện có đó thay vì lặp lại nó.

Quan trọng

Khi xóa hoặc di chuyển một tệp .rst, hãy cập nhật tệp văn bản tương ứng trong thư mục redirects dựa trên phiên bản branch của bạn (ví dụ: 17.0.txt). Để làm điều này, hãy thêm một dòng mới ở cuối phần liên quan (ví dụ: # applications/sales). Trên dòng này, đầu tiên, thêm điểm vào chuyển hướng với vị trí tệp cũ, theo sau là một dấu cách, sau đó thêm điểm ra với vị trí tệp mới hoặc liên quan. Ví dụ, nếu di chuyển tệp unsplash.rst từ applications/websites/website/configuration sang applications/general/integrations, hãy thêm mục sau vào dưới phần # applications/websites:

applications/websites/website/configuration/unsplash.rst applications/general/integrations/unsplash.rst

Cấu trúc tài liệu¶

Sử dụng các cấp độ tiêu đề khác nhau để tổ chức văn bản theo các phần và phần con. Tiêu đề không chỉ được hiển thị trong tài liệu mà còn trên menu điều hướng (chỉ H1) và trên thanh bên "On this page" (từ H2 đến H6).

H1: Tiêu đề trang Tiêu đề trang giúp người đọc nhanh chóng và rõ ràng hiểu được nội dung nói về điều gì. Nội dung trong phần này mô tả nội dung sắp tới theo góc độ kinh doanh, và không nên tập trung nhấn mạnh vào Odoo, vì đây là tài liệu chứ không phải nội dung marketing. Ngay dưới tiêu đề trang (H1), hãy bắt đầu bằng một đoạn mở đầu, giúp người đọc chắc chắn rằng họ đã tìm đúng trang, sau đó giải thích các khía cạnh kinh doanh của chủ đề này trong các đoạn tiếp theo.
	H2: Tiêu đề phần (cấu hình) Phần H2 đầu tiên này nói về việc cấu hình tính năng, hoặc các điều kiện tiên quyết để đạt được một mục tiêu cụ thể.
	H2: Tiêu đề phần (các phần chính) Tạo càng nhiều phần chính tương ứng với số lượng hành động hoặc tính năng cần phân biệt.
		H3: Phần con Các phần con rất phù hợp để đi sâu vào những điểm rất cụ thể.
	H2: Phần tiếp theo

Để viết tiêu đề tốt:

Ngắn gọn: tránh dùng câu hoàn chỉnh, câu hỏi, và tiêu đề bắt đầu bằng "how to".
Không sử dụng đại từ trong tiêu đề, đặc biệt là ngôi thứ hai (you/your).
Sử dụng sentence case. Điều này có nghĩa là bạn chỉ viết hoa:
- chữ cái đầu tiên của tiêu đề hoặc đề mục;
- chữ cái đầu tiên sau dấu hai chấm;
- danh từ riêng (thương hiệu, tên sản phẩm và dịch vụ, v.v.).

Ghi chú

Hầu hết các tiêu đề và đề mục thường đề cập đến một khái niệm và không đại diện cho tên của một tính năng hoặc một model.
Không viết hoa các chữ trong một từ viết tắt nếu chúng không liên quan đến danh từ riêng.
Sử dụng động từ trong đề mục là hoàn toàn ổn vì chúng thường mô tả một hành động.

Xem thêm

Phong cách viết¶

Viết tài liệu không giống với viết blog hay các loại nội dung khác. Người đọc thường có xu hướng lướt qua nội dung để tìm thông tin họ cần. Hãy nhớ rằng tài liệu là nơi để thông tin và mô tả, không phải để thuyết phục và quảng bá.

Mẹo

Tránh sử dụng you càng nhiều càng tốt bằng cách chọn thể mệnh lệnh khi phù hợp. Tuy nhiên, đừng làm phức tạp câu văn chỉ để tránh nói trực tiếp với người đọc.

Example

Ví dụ tốt:

Select the appropriate option from the dropdown menu.

Ví dụ xấu:

You can select the appropriate option from the dropdown menu.

Chính tả¶

Sử dụng chính tả và ngữ pháp tiếng Anh Mỹ (American English) xuyên suốt tài liệu.

Tính nhất quán¶

Sự nhất quán là chìa khóa cho mọi thứ.

Đảm bảo rằng phong cách viết luôn nhất quán. Khi chỉnh sửa nội dung hiện có, hãy cố gắng giữ đúng giọng văn và cách trình bày hiện tại, hoặc viết lại để phù hợp với phong cách riêng của bạn.

Viết hoa¶

Sử dụng sentence case trong tiêu đề.
Viết hoa tên ứng dụng, ví dụ: Odoo Sales, ứng dụng Sales, v.v.
Viết hoa các nhãn (như trường và nút) đúng như cách chúng xuất hiện trong Odoo. Nếu một nhãn được viết toàn bộ bằng chữ hoa, hãy chuyển nó sang sentence case.
Viết hoa chữ cái đầu tiên sau dấu hai chấm nếu đó là một câu hoàn chỉnh.
Tránh viết hoa các danh từ chung, chẳng hạn như "sales order" và "bill of materials", trừ khi bạn đang tham chiếu đến một nhãn hoặc một model.

Thì ngữ pháp¶

Trong tiếng Anh, các mô tả và hướng dẫn thường yêu cầu sử dụng thì hiện tại, trong khi thì tương lai chỉ phù hợp khi một sự kiện cụ thể sẽ xảy ra sau đó.

Example

Ví dụ tốt (thì hiện tại):

Screenshots are automatically resized to fit the content block's width.

Ví dụ xấu (thì tương lai):

When you take a screenshot, remember that it will be automatically resized to fit the content block's width.

Danh sách¶

Danh sách giúp tổ chức thông tin một cách rõ ràng, súc tích và cải thiện khả năng đọc hiểu. Chúng được sử dụng để làm nổi bật các chi tiết quan trọng, hướng dẫn người đọc qua các bước một cách có hệ thống, v.v.

Sử dụng danh sách đánh số khi thứ tự quan trọng, ví dụ: hướng dẫn, quy trình, hoặc các bước phải được thực hiện theo một trình tự nhất định.

Sử dụng danh sách dấu đầu dòng khi thứ tự các mục không quan trọng, ví dụ: danh sách tính năng, trường, tùy chọn, v.v.

Mẹo

Sử dụng văn bản nội tuyến cho các giải thích hoặc khi có từ ba mục danh sách trở xuống.
Kết hợp danh sách có dấu đầu dòng và danh sách đánh số bằng cách sử dụng danh sách lồng nhau khi thích hợp.
Cân nhắc nhóm các bước đơn giản trong cùng một mục danh sách, ví dụ: Đi tới Website ‣ Site ‣ Pages và nhấp vào New.
Chỉ sử dụng dấu chấm ở cuối mục danh sách nếu nó tạo thành một câu hoàn chỉnh.

Example

Danh sách có dấu đầu dòng

Các trường sau có sẵn trên báo cáo Replenishment:

Product: sản phẩm cần được bổ sung
Location: vị trí cụ thể nơi sản phẩm được lưu trữ
Warehouse: kho nơi sản phẩm được lưu trữ
On Hand: số lượng sản phẩm hiện có sẵn

Danh sách đánh số

Để tạo một trang web mới, hãy thực hiện như sau:

- Mở ứng dụng Website, nhấp vào + New ở góc trên bên phải, sau đó chọn Page;
- Hoặc đi tới Website ‣ Site ‣ Pages và nhấp vào New.
Nhập Page Title; tiêu đề này được sử dụng trong menu và URL của trang.
Nhấp vào Create.
Tùy chỉnh nội dung và giao diện của trang bằng trình xây dựng website, sau đó nhấp vào Save.

Xem thêm

Bảng tra cứu nhanh RST: danh sách

Biểu tượng¶

Sử dụng biểu tượng trong hướng dẫn để giúp người đọc xác định các phần tử giao diện người dùng và giảm nhu cầu giải thích dài dòng. Kèm theo mỗi biểu tượng một mô tả trong dấu ngoặc.

Example

Sau khi chế độ nhà phát triển được kích hoạt, có thể truy cập các công cụ dành cho nhà phát triển bằng cách nhấp vào biểu tượng (bug).

Xem thêm

Bảng tra cứu nhanh RST: biểu tượng

Hình ảnh¶

Thêm một vài hình ảnh để minh họa văn bản giúp người đọc hiểu và ghi nhớ nội dung tốt hơn. Tuy nhiên, hình ảnh không bao giờ được thay thế văn bản: hướng dẫn viết cần đầy đủ và rõ ràng tự thân, không phụ thuộc vào các công cụ hỗ trợ trực quan. Hãy sử dụng hình ảnh một cách tiết chế, ví dụ để nhấn mạnh một điểm cụ thể hoặc làm rõ một ví dụ.

Quan trọng

Đừng quên nén các tệp PNG của bạn bằng pngquant.

Ảnh chụp màn hình¶

Ảnh chụp màn hình sẽ tự động được thay đổi kích thước để vừa với chiều rộng của khối nội dung. Điều này có nghĩa là nếu ảnh quá rộng, chúng sẽ không thể đọc được trên các màn hình có độ phân giải thấp hơn. Chúng tôi khuyến nghị tránh chụp ảnh toàn màn hình của ứng dụng trừ khi thực sự cần thiết, và đảm bảo hình ảnh không rộng quá khoảng 768-933 pixel.

Dưới đây là một vài mẹo để cải thiện ảnh chụp màn hình của bạn:

Thay đổi kích thước chiều rộng trình duyệt của bạn, bằng cách thay đổi kích thước cửa sổ hoặc mở công cụ dành cho nhà phát triển của trình duyệt và thay đổi chiều rộng.
Chọn khu vực liên quan thay vì giữ nguyên toàn bộ cửa sổ.
Loại bỏ thông tin không cần thiết và thay đổi kích thước các cột khi phù hợp.

Quan trọng

Không sử dụng các chú thích như hình chữ nhật hoặc mũi tên trên ảnh chụp màn hình. Thay vào đó, hãy cắt hình ảnh để làm nổi bật thông tin liên quan nhất, và đảm bảo các hướng dẫn văn bản rõ ràng và tự giải thích mà không cần dựa vào hình ảnh.

Example

Ví dụ tốt (trình duyệt đã thay đổi kích thước, không có cột thừa, đã điều chỉnh chiều rộng cột, đã cắt):

Ví dụ không tốt (ảnh chụp màn hình toàn chiều rộng):

Tệp media¶

Một tên tệp media:

được viết bằng chữ thường;
phù hợp với nội dung của tệp media. (ví dụ: screenshot-tips.gif);
phân tách các từ bằng dấu gạch nối - (ví dụ: awesome-filename.png).

Mỗi tệp RST có thư mục riêng để lưu trữ các tệp media. Tên thư mục phải giống với tên tệp RST.

Ví dụ, tài liệu doc_filename.rst tham chiếu đến hai hình ảnh được đặt trong thư mục doc_filename.

├── section
│   └── doc_filename
│   │   └── screenshot-tips.gif
│   │   └── awesome-filename.png
│   └── doc_filename.rst

Ghi chú

Trước đây, tên tệp hình ảnh thường được đặt bằng số (ví dụ: feature01.png) và đặt trong một thư mục media duy nhất. Mặc dù được khuyến nghị không đặt tên các hình ảnh mới của bạn theo cách này, nhưng cũng cần thiết không đổi tên các tệp không thay đổi, vì làm như vậy sẽ nhân đôi dung lượng của các tệp hình ảnh đã đổi tên trên kho lưu trữ. Cuối cùng, tất cả chúng sẽ được thay thế khi nội dung tham chiếu đến những hình ảnh đó được cập nhật.

Thẻ ALT¶

Thẻ ALT là một văn bản thay thế cho hình ảnh. Văn bản này được hiển thị nếu trình duyệt không thể hiển thị hình ảnh. Nó cũng hữu ích cho người dùng bị khiếm thị. Cuối cùng, nó giúp các công cụ tìm kiếm, chẳng hạn như Google, hiểu được nội dung của hình ảnh và lập chỉ mục chính xác, từ đó cải thiện SEO.

Các thẻ ALT tốt là:

Ngắn gọn (tối đa một dòng);
Không lặp lại một câu hoặc tiêu đề trước đó;
Một mô tả tốt về hành động đang diễn ra trong hình ảnh;
Dễ hiểu khi đọc to.

Example

Một thẻ ALT phù hợp cho ảnh chụp màn hình sau đây có thể là Kích hoạt chế độ nhà phát triển trong ứng dụng Cài đặt.

Xem thêm

Bảng tra cứu nhanh RST: hình ảnh