Content Guidelines

Đây là bộ quy ước viết nội dung trên website của Viindoo, giúp mọi người viết nội dung với bố cục rõ ràng, đúng nguyên tắc viết văn bản, giúp ích cho hoạt động tối ưu SEO nội dung.

Note

Trước khi áp dụng nguyên tắc trong bài viết này bạn cần đọc kỹ bài viết về cách sử dụng cấu trúc RST để viết nội dung.

RST cheat sheet.

Ngôn ngữ sử dụng

Bài viết Hướng dẫn sử dụng là tài liệu hỗ trợ người dùng cách sử dụng một sản phẩm, hệ thống… cụ thể. Do vậy, nội dung viết cần ngắn gọn, dễ hiểu và chi tiết các bước thực hiện để người dùng có thể thao tác theo. Các từ đã được định nghĩa trong phần mềm cần sử dụng đúng để người dùng đối chiếu.

Chia đoạn

Đoạn văn

Viết nội dung trên website khác với viết sách, người dùng không đủ kiên nhẫn để đọc một đoạn văn quá dài. Mỗi đoạn nội dung trên website thường dài từ 2-4 dòng.

Câu văn

Độ dài của câu văn

  • Tương tự như đoạn văn, một câu văn quá dài vừa không tốt cho người đọc, vừa bị Google đánh giá SEO không tốt. Viết tài liệu là viết các bài ngắn nên cần sử dụng nhiều câu ngắn thay vì một câu dài.

  • Câu văn cần ngắn gọn, hạn chế sử dụng cách viết theo sách như sử dụng dấu “,” hoặc “;” làm cho câu dài ra.

  • Không nên lạm dụng những từ: “Nếu… thì…”; “Tuy… nhưng…”; “Mặc dù… nhưng…”; “Không chỉ… mà còn…” để kéo dài câu.

Sử dụng dấu câu

  • Dùng dấu chấm “.” để kết thúc câu văn thông thường.

  • Không sử dụng dấu chấm “.”, dấu phẩy “,”, hai chấm “:”, chấm phẩy “;” ở cuối các tiêu đề, đề mục của bài viết.

  • Các dấu ngắt câu như chấm “.”, phẩy “,”, hai chấm “:”, chấm phẩy “;”, chấm than “!”, hỏi chấm “?”, ba chấm “…” phải được gõ sát vào từ đứng trước nó, tiếp theo là một dấu trắng nếu sau đó vẫn còn nội dung. Ví dụ:

    • Sai: Trên thanh tìm kiếm ,gõ từ khóa Tuyển dụng.

    • Đúng: Trên thanh tìm kiếm, gõ từ khóa Tuyển dụng.

  • Giữa các từ chỉ dùng một dấu trắng để phân cách. Không sử dụng dấu trắng đầu dòng cho việc căn chỉnh lề.

  • Các dấu mở ngoặc () và mở nháy “” đều phải được hiểu là ký tự đầu từ, do đó ký tự tiếp theo phải viết sát vào bên phải của các dấu này. Tương tự, các dấu đóng ngoặc và đóng nháy phải hiểu là ký tự cuối từ và được viết sát vào bên phải của ký tự cuối cùng của từ bên trái. Ví dụ:

    • Sai: Truy cập vào Ứng dụng để cài đặt mô-đun Tuyển dụng ( hr_recruitment ).

    • Đúng: Truy cập vào Ứng dụng để cài đặt mô-đun Tuyển dụng (hr_recruitment).

Sử dụng 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 chấm.

  • Các danh từ riêng (tên thương hiệu, tên sản phẩm, tên ứng dụng…).

  • Các thuật ngữ của ứng dụng cần viết giống như trong phần mềm. Ví dụ: Năng lực Sản xuất.

Note

  • Không viết hoa các danh từ chung chung khi chúng không được nhắc đến như thuật ngữ, tính năng của phần mềm.

  • Ví dụ: Để tạo một liên hệ mới trong phần mềm, bạn truy cập vào ứng dụng Liên hệ. Từ liên hệ đầu tiên là danh từ chung chung nên không viết hoa, nhưng từ thứ 2 là tên của ứng dụng nên cần viết hoa chữ đầu tiên.

Sử dụng tab

Lưu ý không dùng tab với list:

  • Khi tạo list có đánh số (ordered list) thì các item con của nó phải thụt lề 3 dấu cách thay vì tab.

  • Khi tạo list không đánh số (unordered list) thì các item con của nó phải thụt lề 2 dấu cách thay vì tab.

Tiêu đề, đề mục

Tiêu đề bài viết

  • Tiêu đề (title) bài viết giúp cho người đọc hiểu nhanh và rõ ràng về nội dung bạn đang truyền tải là gì.

  • Tiêu đề mặc định là Heading 1. Mỗi bài viết chỉ sử dụng 1 lần thẻ H1.

  • Tiêu đề cần ngắn gọn, xúc tích, giúp người đọc nắm bắt được nội dung của bài viết.

  • Độ dài Tiêu đề từ 50 đến 60 ký tự.

  • Nội dung của tiêu đề phải chứa từ khóa chính của bài viết. Ví dụ: Bài viết với nội dung hướng dẫn cách tạo báo giá thì tiêu đề cần chứa từ khóa “Báo giá”, từ này cũng được sử dụng xuyên suốt trong bài viết.

  • Không sử dụng đại từ nhân xưng trong tiêu đề. Ví dụ như: tôi, chúng tôi, của bạn…

Đề mục bài viết

  • Đề mục (Heading) là các mục lớn - ý chính của bài viết, xây dựng thành cấu trúc nội dung của bài viết.

  • Các phân cấp lần lượt của thẻ heading là từ Heading 1 (Title) đến Heading 6.

  • Heading 2 (H2): Mô tả ngắn gọn cho nội dung chính bổ trợ cho thẻ H1. Một bài viết thường sử dụng từ 3-5 thẻ H2.

  • Heading 3 (H3): Mô tả chi tiết cho từng ý trong bài được cụ thể hơn. H3 nằm bên trong H2.

  • Lưu ý:

    • Một bài viết có thể không có H3, nhưng nếu có H3 thì trước nó bắt buộc phải có H2.

    • Không viết tắt, sử dụng số trong tiêu đề, đề mục bài viết. Cần viết rõ là một, hai, ba… thay vì dùng 1, 2, 3…

Cấu trúc bài viết

Bất kể là bài viết ở dạng nội dung nào (Hướng dẫn sử dụng, Blogs, PR news…) cũng cần có bố cục rõ ràng, phải có phần mở đầu, thân bài và kết luận.

Phần mở đầu

Trong phần mở đầu bài viết có 2 yếu tố đặc biệt quan trọng giúp người đọc quyết định có đọc tiếp nội dung bài viết phía dưới hay không? Đó chính là tiêu đề và đoạn mô tả ngắn về toàn bài.

  • Tiêu đề bài viết: sử dụng thẻ H1.

  • Đoạn mô tả: tóm lược nội dung của bài viết. Giới hạn từ Từ 290 đến 325 ký tự.

Thân bài

Nội dung phần thân bài cần được chia nhỏ thành các ý rõ ràng, giúp người đọc có thể đọc nhanh và tìm kiếm nhanh vấn đề mà họ cần.

  • Tiêu đề mục 1: sử dụng thẻ H2.

    • Nội dung đoạn 1.

    • Hình ảnh hoặc video minh họa.

    • Liên kết bài viết: dẫn link liên quan với anchor liên quan. Ưu tiên liên kết chéo những bài viết có cùng chủ đề để giữ chân người đọc lâu hơn trên website.

    • Mục phụ (nếu có): sử dụng thẻ H3.

  • Tiêu đề mục 2: sử dụng thẻ H2.

    • Nội dung đoạn 2.

    • Hình ảnh hoặc video minh họa.

    • Liên kết bài viết.

    • Mục phụ (nếu có): sử dụng thẻ H3.

  • Đối với một số bài viết có nội dung dạng Landing page, Blogs… nên sử dụng Call to Action nhằm kêu gọi hành động, có thể trình bày dưới dạng text hoặc button. Ví dụ: Xem thêm, Tìm hiểu thêm, Đăng ký ngay, Dùng thử ngay…

Xem thêm: Hướng dẫn viết Tiêu đề với cấu trúc rst.

Kết bài

Viết một đoạn ngắn khái quát và kết thúc lại vấn đề bài viết đã chia sẻ. Đừng quên nhắc đến thương hiệu Viindoo trong bài viết.

Dẫn link xem thêm các bài viết liên quan khác.

Hình ảnh

Thêm một vài hình ảnh để minh họa nội dung văn bản giúp cho người đọc hiểu và ghi nhớ dễ hơn.

Chụp ảnh giao diện phần mềm

Hình ảnh minh họa cho phần mềm Viindoo cần sử dụng đúng giao diện theme Viindoo (menu xanh, nút màu tím…).

Khung hình

  • Chụp toàn cảnh: Bao quát toàn bộ, không có phần thừa như các tab, địa chỉ URL của trình duyệt.

Ảnh khung hình
  • Chụp một phần: Cân đối, không có phần thừa.

  • Sử dụng border: 1px cho ảnh nền trắng, không có đường viền xung quanh.

Ảnh khung hình border

Chỉ dẫn

  • Đường chỉ dẫn mũi tên: dài khoảng 1cm, màu đỏ, cỡ 1, chếch khoảng 45 độ từ Phải qua trái hoặc ngược lại.

  • Khoanh hình: hình chữ nhật màu đỏ, căn đều lề 4 bên trên dưới, phải trái.

Ảnh khung căn đều lề 4 bên trên dưới, phải, trái
  • Đường dẫn: khi viết hướng dẫn chỉ đường đến một tính năng thì phải chỉ đúng thực tế cấu trúc menu trong phần mềm, sử dụng chữ in đậm, viết hoa chữ cái đầu tiên cho các menu. Ví dụ:
    • Thay vì viết: Vào Mô đun Kho vận ‣ chọn Cấu hình ‣ chọn Sản phẩm ‣ chọn Nhóm sản phẩm , chọn nhóm sản phẩm cần cấu hình…

    • Viết thành: Vào Mô đun Kho vận ‣ Cấu hình ‣ Sản phẩm ‣ Nhóm sản phẩm, chọn nhóm sản phẩm cần cấu hình…

Xem thêm: Hướng dẫn viết đường dẫn với cấu trúc rst.

  • Thuật ngữ, nút trong phần mềm: sử dụng chữ in đậm, không in nghiêng, không đưa vào dấu ngoặc kép “” cho các thuật ngữ, nút tương ứng trong phần mềm. Ví dụ: Bấm vào nút Tạo để tạo mới một nhân viên.

  • Hướng dẫn: viết trên tài liệu, không viết trên hình ảnh.

Đặt tên cho ảnh

Đặt tên cho ảnh theo cú pháp: ten-anh.language.jpg

Trong đó:

  • ten-anh: dựa theo nội dung của ảnh để đặt tên. Tên của ảnh viết thường, không dấu, các ký tự cách nhau bởi dấu gạch ngang “-”. Tên của ảnh phải chứa từ khóa và nhắc tên thương hiệu: Ví dụ: Ảnh chụp giao diện tổng quan của ứng dụng CRM → giao-dien-tong-quan-ung-dung-viindoo-crm.

  • language: ngôn ngữ gốc sử dụng trong ảnh. Ở đây dùng “vi” cho ảnh giao diện tiếng Việt, “en” cho ảnh giao diện tiếng Anh.

  • jpg: định dạng của ảnh.

Xem thêm: Bộ từ khóa Viindoo.

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ể kết xuất hình ảnh. Giúp các công cụ tìm kiếm như Google hiểu được hình ảnh về cái gì và lập chỉ mục hình ảnh đó một cách chính xác. Việc này giúp ích đáng kể cho hoạt động tối ưu SEO.

Thẻ ALT tốt là:

  • Ngắn gọn (tối đa một dòng).

  • Mô tả đúng nội dung của hình ảnh, hướng đến các từ khóa người dùng tìm kiếm trên Google (là một cụm từ chứ không phải một câu).

  • Có thể hiểu một cách dễ dàng khi đọc lên.

Thông thường, thẻ ALT sẽ trùng với tên ảnh.

Ví dụ:

  • Tên ảnh: giao-dien-tong-quan-ung-dung-viindoo-crm.jpg

  • Thẻ ALT: Giao diện tổng quan ứng dụng Viindoo CRM

Cách hiển thị thẻ ALT khi ảnh bị lỗi:

Cách hiển thị thẻ ALT khi ảnh bị lỗi

Xem thêm: Cú pháp chèn ảnh với cấu trúc rst.

Tên của thư mục, bài viết

  • Được viết thường.

  • Ngăn cách các từ bằng dấu gạch ngang “-”. Ví dụ: how-to-create-viindoo-instance

  • Không được sử dụng dấu “_” trong các file, folder, tiêu đề bài viết, tên ảnh, tên video, đường dẫn áp dụng cho tài liệu hướng dẫn sử dụng.

  • Không sử dụng ký tự đặc biệt, ví dụ: “/”, “&”, “?”

  • Không viết theo cú pháp “01.tong-quan-ke-toan”, cần viết “tong-quan-ke-toan”.

Sử dụng Email

Để hạn chế việc bị spam email, tất cả các nội dung đăng tải trên website không sử dụng email có thật (email cá nhân), email có tên miền viindoo.com hay erponline.vn ngay sau ký hiệu @. Hãy sử dụng các email không có thật để minh họa cho nội dung bài viết của mình. Ví dụ: @example.com, @example.viindoo.com, @tencongty.com,…

Một số lưu ý cho nội dung hướng dẫn sử dụng

  • Chế độ Nhà phát triển (debug): Không bật chế độ debug khi viết hướng dẫn sử dụng người dùng. Khi viết đến tính năng cần debug hãy làm mẹo (tips) dẫn đến bài viết hướng dẫn Kích hoạt chế độ nhà phát triển để tránh gây khó hiểu cho người dùng và không làm bài viết của bạn quá dài.

Git & Github

Commit & PR

  • Nội dung commit phải tham chiếu tới issue nếu có bằng cách sử dụng #xxx (xxx là id của issue).

  • Nội dung commit phải chứa close #xxx (xxx là id của issue) để tự động close issue nếu cần.

  • Commit phải có nội dung rõ ràng nhưng ngắn gọn và xúc tích.

  • Nội dung của commit phải hoàn toàn bằng tiếng Anh.

  • Tiền tố của nội dung commit phải tuân thủ theo quy ước sau:

    • [WIP] = work in progress, sử dụng cho các commit đang ở trong quá trình thực hiện nội dung, phù hợp trong các công việc dài ngày mà vẫn phải commit hàng ngày. Lưu ý: nếu đang làm dở, chưa cần review thì bắt buộc phải đặt WIP.

    • [IMP]: sử dụng trong trường hợp commit cải tiến, bổ sung.

    • [FIX]: sửa lỗi, sử dụng trong trường hợp commit để sửa lỗi.

    • [I18N]: cho các vấn đề liên quan đến dịch thuật.

    • [UPG]: nâng cấp bài viết lên phiên bản Odoo sau.

    • [REM]: xóa file.

    • [REN]: đổi tên file, category.

    • [ADD]: bổ sung tính bài viết, category.

    • [MISC]: các vấn đề khác.

  • Một Pull Request (PR) tương ứng với một tính năng,chia càng nhỏ càng tốt.

  • Đối với người kiểm duyệt nội dung phải thực hiện hoặc yêu cầu tác giả thực hiện rebase (nếu có commits behind) trước khi merge.

  • Một PR nếu có commits behind thì phải thực hiện rebase trước khi request review.

  • Tiền tố cho title của PR cũng tương tự như Commit ở trên chỉ khác là bổ sung thêm phiên bản của Odoo.

  • Ví dụ: [FIX][13.0] Điều chỉnh lại nội dung bài viết Hóa đơn & Thanh toán…

Quy ước về tên branch

  • v<odoo_version>_add_docs_<tinh_nang>: thêm mới một bài viết HDSD. VD: v14_add_docs_to_attendance_device

  • v<odoo_version>_fix_<tinh_nang>: nếu là fix bug cho một module. VD: v14_fix_to_attendance_device

  • v<odoo_version>_upg_<tinh_nang>: nếu là nâng cấp phiên bản (odoo version) cho một module. VD: v14_upg_to_attendance_device

  • v<odoo_version>_rem_<tinh_nang>: nếu là remove module. VD: v14_rem_to_attendance_device

  • v<odoo_version>_imp_<tinh_nang>: nếu là cải tiến module. VD: v14_imp_to_attendance_device

  • v<odoo_version>_<tinh_nang>: nếu là một bộ tính năng nào đó. Lưu ý <tinh_nang> cần ngắn gọn và súc tích.

Lưu ý

  • Cấu hình đúng email và name trước khi commit.

  • Thực hiện yêu cầu review nếu PR đã làm xong và cần review. Việc này sẽ giảm thời gian cho reviewer phải đặt câu hỏi kiểu như “làm xong chưa?”.

  • PR phải có miêu tả rõ ràng hoặc phải gắn tới link mà có miêu tả rõ ràng trong đó.