Tech guidelines

Giới thiệu

Trang cộng đồng của 123HOST được thành lập với mục đích phi lợi nhuận. Là nơi để mọi người cùng chia sẻ và học hỏi kiến thức về SysAdmin, Devops, Developer.

Dưới đây là hướng dẫn cũng như quy định viết bài:

Quy trình viết bài

Các Tác giả sau khi đăng ký viết bài với 123HOST Community Team (CT), cần thực hiện viết bài theo các bước sau.

• Bước 1: Đề xuất chủ đề muốn viết, và tiêu đề bài viết. Ví dụ viết về Ansible. Tiêu đề là Hướng dẫn cài đặt Ansible trên Ubuntu 20.04

• Bước 2: CT sẽ duyệt tiêu đề và chủ đề.

• Bước 3: Sau khi được duyệt, Tác giả thực hiện liên outline cho bài viết và gửi CT.

• Bước 4: CT kiểm tra, chỉnh sửa và duyệt outline. Tác giả cũng phối hợp với community team để có được outline như ý muốn.

• Bước 5: Outline sau khi được duyệt, CT sẽ đề xuất mức trả phí cho bài viết. Tuy theo độ khó và độ dài của mỗi bài viết mà sẽ có mức chi phí đề xuất khác nhau. Tác giả có thể đồng ý hoặc đàm phán lại mức chi phí theo mong muốn.

• Bước 6: Tác giả thực hiện viết bài sau khi đã thống nhất outline và chi phí bài viết với CT.

• Bước 7: Tác giả gửi bài viết sau khi viết. CT sẽ chỉnh sửa, tối ưu SEO, duyệt bài.

• Bước 8: Tác giả đồng ý với bài viết sau khi được chỉnh sửa (nếu có). Bài viết được đăng trên trang cộng đồng.

Community Team luôn tôn trọng ý kiến của tác giả. Và thực hiện chỉnh sửa để bài viết đạt chất lượng tốt nhất. Tác giả có thể thảo luận với CT để nội dung, chi phí bài viết như mong muốn của mình.

123HOST giữ bản quyền của bài viết. Tuy nhiên các tác giả đều có profile riêng kèm danh sách bài viết, thành tích mà mình đã đóng góp. Ví dụ https://123host.vn/community/user/ngocdang

Tech GuideLines

Bài viết phải dễ đọc, phù hợp với nhiều cấp độ người đọc khác nhau

• Các bài viết được viết theo cách rõ ràng và chi tiết nhất có thể, để mọi đối tượng với trình độ khác nhau có thể đọc hiểu và làm theo.

• Người đọc chỉ cần xem bài viết đang đọc là có thể thực hiện các thao tác đề cập trong bài mà không cần tìm thêm các tài liệu bên ngoài.

• Bài viết cũng cần giải thích hoặc dẫn link các khái niệm ở mức cơ bản, nhằm đảm bảo người đọc có thể hiểu các khái niệm liên quan.

• Bài viết không được copy hoặc chỉnh sửa từ các bài viết đã có sẵn.

Viết phải đúng về mặt kỹ thuật

• Bài viết phải đúng và chính xác về mặt kỹ thuật, cũng như tuân theo các best-practices.

• Mỗi lệnh tác giả nên giải thích lệnh dùng để làm gì, đối số dòng lệnh nếu có cũng nên giải thích công dụng.

• Mỗi đoạn trong tập tin cấu hình sẽ làm gì và tại sao phải cần thay đổi.

• Tên phần mềm phải đúng chính tả. Ví dụ phpMyAdmin, GlusterFS, WordPress.

Tác giả cần phải kiểm tra lại các thao tác trong bài viết có thể tiến hành thành công hoàn toàn ở môi trường mới. Điều này đảm bảo tính chính xác và xác định các bước còn thiếu.

Các biên tập viên của chúng tôi cũng kiểm tra các bài viết này như một phần của quá trình review để đảm bảo người đọc có trải nghiệm học tập tuyệt vời mà không gặp vấn đề nào.

Nội dung & bản quyền

• Tất cả nội dung phải được tác giả tự viết. Output của lệnh phải được tác giả copy từ chính terminal mà tác giả thực hiện. Như vậy nội dung là tự viết, không được copy từ nguồn khác hoặc copy rồi dịch hay chỉnh sửa lại.
• Bài viết một khi đăng tải và thành toán thành công thì thuộc sở hữu của 123HOST. Không được đăng tải lại nội dung của bài viết trên website khác.
• Không được đề cập nhà cung cấp dịch vụ cùng ngành trong bài viết.
• Hạn chế tối đa việc liên kết với link bên ngoài khi viết bài.

Thực tế và hữu ích

• Phải đảm bảo rằng người đọc thực hiện thành công như hướng dẫn nếu làm đủ và đúng các bước theo thứ tự.

• Điều này có nghĩa là tác giả phải cung cấp đầy đủ các yêu cầu (requirement) cần thiết, hoặc hướng dẫn cài đặt trước các gói cần thiết trước khi bắt đầu thao tác nào đó (nếu có).

• Việc cung cấp link này chỉ cung cấp link nội bộ, cùng hệ thống, chỉ được cung cấp link bên ngoài vào trường hợp thu thập thêm thông tin về một khái niệm nào đó và link để tải phần mềm.

Ngôn ngữ và cách xưng hô

• Các bài viết đều hướng đến thân thiện với người đọc tuy nhiên phải trang trọng về ngôn ngữ.

• Nội dung bài viết không dùng biệt ngữ, từ lóng, câu nói đùa và emoji. Bởi vì chúng tôi hướng đến mọi người đọc, chúng tôi hướng đến một giọng điệu phù hợp với mọi người đọc thuộc các văn hóa, vùng miền khác nhau.

• Không giống khi các bạn viết blog bình thường, ở đây chúng ta không dùng ngôi thứ nhất số ít (Ví dụ "Tôi cần..."). Thay vào đó chúng ta sử dụng ngôi thứ hai (Ví dụ "Bạn sẽ chỉnh sửa....") để người đọc nhập tâm và dễ tập trung khi đọc hơn. Một số trường hợp cần để nhất mạnh thì chúng ta có thể sử dụng ngôi thứ ba số nhiều ( Ví dụ "Chúng ta...").

Khuyến khích ngôn ngữ tạo động lực học tập. Ví dụ: thay vì "Bạn sẽ học cách cài đặt Kubernetes", nên sử dụng "Trong bài hướng dẫn này, bạn sẽ tự tay cài đặt một Kubernetes Cluster...". Điều này thúc đẩy tinh thần người đọc và tập trung đến cùng để hoàn thành các mục tiêu trong bài viết đề ra.

Ouline tutorial mẫu

Tiêu đề

Giới thiệu (h3)

Yêu cầu(requirement) (h2)

Bước 1... (h2)

Bước 2... (h2)

Bước n... (h2)

Tổng kết (h2)

Tiêu đề

Một tiêu đề thường nằm trong mẫu:

Hướng dẫn <Công việc> <Tên Phần Mềm> trên <Tên distro/hệ điều hành>

Ví dụ: Hướng dẫn cài đặt máy chủ web Apache trên CentOS 8

Khi chọn tiêu đề thì cần hình dung thử rằng người đọc sẽ hiểu mục tiêu chính cần hoàn thành khi đọc xong bài viết là gì. Hạn chế việc dùng tiêu đề không rõ ràng như "Cách cài đặt và cấu hình Apache".

Nếu bài viết dạng cài đặt theo distro, bạn có thể viết nhiều biến thể bài viết cho nhiều distro khác nhau. Giao diện xem bài viết sẽ cho phép người dùng chọn distro phù hợp với mình. Ví dụ:

Sau khi bổ sung biến thể cho các distro khác, bạn sẽ được bonus thêm chi phí.

Giới thiệu (heading 3)

Phần đầu tiên của mỗi bài viết là phần giới thiệu, thông thường chỉ dài 1 đến 3 đoạn văn ngắn.

Mục đích của phần giới thiệu là để thúc đẩy người đọc, đặt kỳ vọng và tóm tắt những gì người đọc sẽ làm trong bài viết. Phần giới thiệu của bạn nên trả lời các câu hỏi sau:

• Hướng dẫn về vấn đề gì gì? Phần mềm nào có liên quan và mỗi thành phần làm chức năng gì? (mô tả ngắn gọn)

• Tại sao người đọc nên tìm hiểu chủ đề này? Lợi ích của việc sử dụng phần mềm cụ thể này trong bài viết này là gì? Một số lý do thực tế khiến người đọc nên làm theo hướng dẫn này là gì?

• Người đọc sẽ làm gì hoặc tạo gì theo bài viết này?

• Người đọc sẽ đạt được gì khi họ hoàn thành các thao tác theo bài viết? Họ sẽ có những kỹ năng mới nào? Họ sẽ làm được gì mà trước đây họ không thể làm được?

Yêu cầu (heading 2)

Mục đích là đưa ra các yêu cầu về thao tác (ví dụ update hệ điều hành) hoặc yêu cầu về kiến thức (ví dụ phải thành thạo Python) trước khi có thể thực hiện được bài viết này. Một số gợi ý:

• Số lượng server, loại distro, các thiết lập ban đầu của server, cấu hình phần cứng yêu cầu (CPU, RAM, Diskspace).

• Quyền root/non-root, quyền sudo...

• Thiết lập DNS, SSL.

• Update kernel/ hệ điều hành trước.

Nếu đã có bài viết tại trang Cộng đồng hướng dẫn rồi thì bạn có thể link về bài viết đó.

Các bước thực hiện (heading 2)

Các bước thực hiện phải rõ ràng, dễ làm theo. Tiêu đề của các bước không quá dài.

Tổng kết (heading 2)

Tổng kết lại quá trình cài đặt/ cấu hình. Các lưu ý hoặc các thông tin mở rộng. Lời chúc thành công.

Format bài viết

123HOST Community sử dụng chuẩn markdown để soạn thảo bài viết. Tác giả cần soạn thảo theo chuẩn này. Đặc biệt là định dạng về dòng lệnh (root hoặc non-root hoặc prefix), nội dung file phải theo quy định.

• Xem demo: https://123host.vn/tutorial/markdown

• Xem hướng dẫn: https://123host.vn/community/tutorial/huong-dan-su-dung-markdown-de-viet-bai-tutorial.html