GALAXY TECH
Chuyên gia Công nghệ
Thứ ba, 27/10/2020 | 00:00 GMT+7

DigitalOcean rất vui được tiếp tục xây dựng bộ sưu tập các bài báo kỹ thuật liên quan đến quản trị server và kỹ thuật phần mềm. Để đảm bảo các bài viết DigitalOcean có chất lượng và phong cách nhất quán, ta đã phát triển các nguyên tắc sau.

Có ba phần trong hướng dẫn này:

  • Phong cách , cách tiếp cận cấp cao của ta để viết hướng dẫn kỹ thuật
  • Cấu trúc , giải thích về bố cục và nội dung của ta
  • Định dạng và Thuật ngữ , một tham chiếu Đánh dấu và thuật ngữ

Để được xuất bản nhanh chóng, ta khuyên bạn nên đọc toàn bộ phần Kiểu và Cấu trúc trước khi bắt đầu làm việc với bài viết của bạn .

Bạn có thể sử dụng phần Định dạng của hướng dẫn này cùng với trình xem trước Markdown của ta làm tài liệu tham khảo trong khi viết bài viết của bạn .

Ta cũng có hướng dẫn về các phương pháp kỹ thuật tốt nhất nêu ra các đề xuất tập trung vào công nghệ của ta .

Ta đã phát triển các mẫu bài viết ở định dạng Markdown mà bạn có thể sử dụng làm điểm bắt đầu cho bài viết của bạn . Ta thực sự khuyên bạn nên sử dụng một trong những mẫu này để lập kế hoạch và phát triển bài viết của bạn .

Đọc tiếp để tìm hiểu về phong cách bài viết của ta .

Phong cách

Các bài viết DigitalOcean không sử dụng một sổ tay kiểu cụ thể như Chicago Manual of Style. Thay vào đó, ta cố gắng đảm bảo tất cả các hướng dẫn DigitalOcean là:

  • Toàn diện và được viết cho tất cả các cấp độ kinh nghiệm
  • Kỹ thuật chi tiết và chính xác
  • Thực tế, hữu ích và khép kín
  • Thân thiện nhưng trang trọng

Những nguyên tắc này hướng dẫn tác giả tạo các bài báo, hướng dẫn và các tài liệu học tập khác giúp mọi người giải quyết vấn đề của họ và phát triển với quyền là nhà phát triển.

Toàn diện và được viết cho tất cả các cấp độ kinh nghiệm

Các bài báo của ta được viết rõ ràng và chi tiết nhất có thể mà không đưa ra giả định về kiến thức nền tảng của người đọc.

Ta bao gồm rõ ràng mọi lệnh mà người đọc cần để đi từ kết nối SSH đầu tiên của họ trên một server hoàn toàn mới đến cài đặt hoạt động cuối cùng. Ta cũng cung cấp cho người đọc tất cả các giải thích và thông tin cơ bản mà họ cần để hiểu hướng dẫn. Mục đích là để độc giả của ta tìm hiểu các khái niệm, không chỉ copy paste mã và lệnh.

Ta tránh các từ như “đơn giản”, “đơn giản”, “dễ dàng”, “đơn giản”, “rõ ràng” và “đơn giản” vì những từ này tạo ra giả định về kiến thức của người đọc. Trong khi các tác giả sử dụng những từ này để khuyến khích và thúc đẩy người đọc thông qua các chủ đề đầy thách thức, chúng thường có tác dụng ngược lại; một độc giả nghe thấy điều gì đó “dễ dàng” có thể thất vọng khi họ gặp phải vấn đề. Thay vào đó, ta khuyến khích độc giả của bạn bằng cách cung cấp những lời giải thích mà họ cần để thành công.

Kỹ thuật chi tiết và chính xác

Các bài báo của ta chính xác về mặt kỹ thuật và tuân theo các phương pháp hay nhất trong ngành. Chúng cũng cung cấp nhiều thông tin chi tiết hơn là chỉ mã và lệnh. Ta không cung cấp khối lớn cấu hình hoặc mã chương trình và yêu cầu người đọc dán nó vào editor của họ, tin tưởng rằng nó hoạt động với ta . Ta cung cấp tất cả các chi tiết cần thiết để người đọc hiểu được nó.

Mọi lệnh phải có giải thích chi tiết, bao gồm các tùy chọn và cờ khi cần thiết. Mỗi khối mã phải mô tả những gì nó làm và tại sao nó hoạt động theo cách đó. Khi bạn yêu cầu trình đọc thực thi một lệnh hoặc sửa đổi file cấu hình, trước tiên hãy giải thích chức năng của nó và lý do bạn yêu cầu trình đọc thực hiện những thay đổi đó.Những chi tiết này cung cấp cho người đọc nền tảng họ cần để phát triển kỹ năng của bạn .

Các tác giả kiểm tra các hướng dẫn của họ đảm bảo chúng hoạt động theo chúng chính xác như được viết trên các server 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 ta cũng kiểm tra các bài viết này như một phần của quá trình đánh giá đảm bảo người đọc có trải nghiệm học tập tuyệt vời.

Thực tế, hữu ích và khép kín

Khi người đọc đã hoàn thành bài viết DigitalOcean, họ nên cài đặt, xây dựng hoặc cài đặt một cái gì đó từ đầu đến cuối. Ta nhấn mạnh một cách tiếp cận thực tế: ở cuối bài viết, người đọc nên có một môi trường hữu dụng hoặc một ví dụ để xây dựng.

Điều này có ý nghĩa gì đối với người viết là bài báo của họ nên bao quát chủ đề một cách thấu đáo. Tác giả nên liên kết đến các bài viết DigitalOcean hiện có, nếu có, để cài đặt các yêu cầu mà người đọc nên làm theo trước khi bắt đầu hướng dẫn và liên kết đến các bài viết DigitalOcean có sẵn để cung cấp thêm thông tin trong phần nội dung của hướng dẫn. Tác giả chỉ nên gửi người đọc ra ngoài trang web để thu thập thông tin nếu không có bài viết DigitalOcean hiện có và thông tin không thể được thêm vào bài viết trực tiếp trong một bản tóm tắt ngắn.

Thân thiện nhưng trang trọng

Hướng dẫn của ta hướng đến một giọng điệu thân thiện nhưng trang trọng. Điều này nghĩa là các bài viết không bao gồm biệt ngữ, meme, tiếng lóng quá mức, biểu tượng cảm xúc hoặc trò đùa. Khi ta viết cho khán giả global , ta hướng đến một giai điệu phù hợp với các ranh giới ngôn ngữ và văn hóa.

Không giống như các bài đăng trên blog, ta không sử dụng ngôi thứ nhất số ít (ví dụ: “Tôi nghĩ…”). Thay vào đó, ta khuyến khích sử dụng ngôi thứ hai (ví dụ: “Bạn sẽ cấu hình…”) để giữ sự tập trung vào người đọc và những gì họ sẽ đạt được. Trong một số trường hợp, ta sẽ sử dụng ngôi thứ nhất số nhiều (ví dụ: “ Ta sẽ cài đặt…” “).

Ta khuyến khích ngôn ngữ tạo động lực tập trung vào kết quả. Ví dụ: thay vì "Bạn sẽ học cách cài đặt Apache", hãy thử "Trong hướng dẫn này, bạn sẽ cài đặt Apache". Điều này thúc đẩy người đọc và tập trung vào mục tiêu họ cần hoàn thành.

Cuối cùng, ngôn ngữ của các hướng dẫn của ta tôn vinh những trải nghiệm đa dạng của con người và tuân theo Luật ứng xử cộng đồng của ta . Điều đó nghĩa là ta tránh ngôn ngữ xúc phạm hoặc nội dung khác liên quan đến (nhưng không giới hạn) tuổi tác, khuyết tật, dân tộc, nhận dạng hoặc biểu hiện giới tính, mức độ kinh nghiệm, quốc tịch, đa dạng thần kinh, ngoại hình cá nhân, chủng tộc, tôn giáo, đảng phái chính trị, tình dục định hướng, tình trạng kinh tế xã hội hoặc lựa chọn công nghệ.

Kết cấu

Các bài viết DigitalOcean có cấu trúc nhất quán, bao gồm phần mở đầu, phần kết luận và bất kỳ yêu cầu nào cần thiết để người đọc bắt đầu. Tuy nhiên, cấu trúc cụ thể tùy thuộc vào từng loại bài báo.

Các hướng dẫn thủ tục hướng dẫn người đọc hoàn thành một nhiệm vụ phức tạp. Cấu trúc của một trong những bài viết này trông như thế này:

  • Tiêu đề (Tiêu đề cấp 1)
  • Giới thiệu (tiêu đề cấp 3)
  • Mục tiêu (Tùy chọn)
  • Yêu cầu (Tiêu đề cấp 2)
  • Bước 1 - Thực hiện Điều đầu tiên (Tiêu đề cấp 2)
  • Bước 2 - Làm điều tiếp theo (tiêu đề cấp độ 2)
  • …
  • Bước n - Thực hiện Điều cuối cùng (Tiêu đề cấp 2)
  • Kết luận (Tiêu đề cấp 2)

Các bài viết khái niệm sẽ có tiêu đề, phần mở đầu và phần kết luận, nhưng có thể không phải lúc nào cũng có phần yêu cầu , phần Mục tiêu và có thể không tuân theo quy ước "Bước":

  • Tiêu đề (Tiêu đề cấp 1)
  • Giới thiệu (tiêu đề cấp 3)
  • Yêu cầu (tùy chọn) (Tiêu đề cấp 2)
  • Thực hiện Điều đầu tiên (Tiêu đề cấp 2)
  • Làm Điều Tiếp theo (Tiêu đề Cấp 2)
  • …
  • Thực hiện Điều cuối cùng (Tiêu đề cấp 2)
  • Kết luận (Tiêu đề cấp 2)

Một số bài báo tập trung hơn vào một nhiệm vụ hoặc giải pháp cụ thể rất nhỏ và chúng thường sẽ có tiêu đề, một câu giới thiệu nhỏ và kết luận ở cuối bài.Các bài báo đó sẽ có cấu trúc như sau:

  • Tiêu đề (Tiêu đề cấp 1)
  • Đoạn giới thiệu
  • Yêu cầu (tùy chọn) (Tiêu đề cấp 2)
  • Nội dung bài viết
  • Đoạn kết luận

Các mẫu bài viết của ta có cấu trúc này đã được viết sẵn cho bạn trong Markdown và ta khuyến khích bạn sử dụng các mẫu này làm điểm khởi đầu cho các bài viết của bạn .

Tiêu đề

Khi bạn viết tiêu đề của bạn , hãy suy nghĩ kỹ về những gì người đọc sẽ đạt được khi làm theo hướng dẫn của bạn. Cố gắng đưa mục tiêu của hướng dẫn vào tiêu đề, không chỉ (các) công cụ mà người đọc sẽ sử dụng để thực hiện mục tiêu đó.

Tiêu đề điển hình cho hướng dẫn thủ tục tuân theo định dạng sau: Cách <Hoàn thành công việc> với <Phần mềm> trên <Danh sách lệnh> .

Ví dụ: nếu hướng dẫn của bạn là về cài đặt web server Caddy, thì mục tiêu có thể là lưu trữ một trang web . Nếu hướng dẫn của bạn là về cài đặt FreeIPA, mục tiêu có thể là cài đặt xác thực Linux tập trung .

Các tiêu đề bao gồm mục tiêu (như “ Cách tạo trang trạng thái với cache ẩn trên Debian 8 ”) thường mang lại nhiều thông tin hơn cho người đọc so với tiêu đề không có (như “Cách cài đặt và cài đặt cache ẩn trên Debian 8”).

Phần đầu tiên của mỗi bài viết là phần Giới thiệu , thường dài từ một đến ba đoạ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ề cái gì? Phần mềm nào liên quan, và mỗi thành phần làm gì (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 cấu hình 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ì trong hướng dẫn này? Họ đang cài đặt một server và sau đó thử nghiệm nó? Họ có đang xây dựng một ứng dụng và triển khai nó không? Hãy cụ thể, vì điều này cung cấp động lực mà người đọc cần và khiến họ hào hứng với chủ đề.
  • Người đọc sẽ đạt được gì khi họ hoàn thành? 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?

Trả lời những câu hỏi này trong phần giới thiệu của bạn cũng sẽ giúp bạn thiết kế một hướng dẫn rõ ràng và tập trung vào người đọc, vì bạn sẽ sắp xếp các bước

Giữ sự tập trung vào người đọc và những gì họ sẽ hoàn thành. Thay vì sử dụng các cụm từ như “ ta sẽ học cách làm”, hãy sử dụng các cụm từ như “bạn sẽ cấu hình” hoặc “bạn sẽ xây dựng”. Điều này giúp thúc đẩy người đọc và khiến họ hào hứng với chủ đề của bạn. Ngoài ra, hãy tập trung vào vấn đề mà người đọc đang giải quyết hơn là công nghệ. Ví dụ: nếu một hướng dẫn về xây dựng một dự án với React, bạn có thể tập trung phần giới thiệu của bạn vào dự án hơn là giải thích React là gì và lịch sử của nó.

Bàn thắng

Một số hướng dẫn thủ tục lớn hơn sử dụng phần Mục tiêu tùy chọn để tách bối cảnh, giải thích cơ bản và động lực của hướng dẫn khỏi các chi tiết của cấu hình cuối cùng. Bạn chỉ nên sử dụng phần này nếu hướng dẫn của bạn yêu cầu nhiều server , có một ngăn xếp phần mềm lớn hoặc có mục đích, phương pháp hoặc kết quả đặc biệt phức tạp.

Một số ví dụ điển hình bao gồm phần giới thiệu của hướng dẫn Prometheus này và các mục tiêu của hướng dẫn Pydio này .

Hầu hết các hướng dẫn sẽ không có phần Mục tiêu .

Yêu cầu

Phần Yêu cầu của các bài viết DigitalOcean có định dạng và mục đích rất cụ thể.

Mục đích là để giải thích chính xác những gì người đọc nên có hoặc làm trước khi họ làm theo hướng dẫn hiện tại. Định dạng là một danh sách có dấu đầu dòng mà người đọc có thể sử dụng làm danh sách kiểm tra. Mỗi dấu đầu dòng phải liên kết đến một hướng dẫn DigitalOcean hiện có bao gồm nội dung cần thiết nếu có. Điều này cho phép bạn dựa vào nội dung hiện có được biết là hoạt động thay vì bắt đầu từ đầu.

Hệ thống và hướng dẫn DevOps của ta đưa người đọc từ triển khai mới của hình ảnh phân phối vani đến cài đặt hoạt động, vì vậy họ nên bắt đầu với kết nối SSH đầu tiên với server hoặc bao gồm hướng dẫn tiên quyết.

Yêu cầu chung cho quản trị hệ thống và hướng dẫn DevOps bao gồm:

  • Số lượng server cần thiết, bao gồm phân phối, cài đặt server ban đầu và bất kỳ tùy chọn cần thiết bổ sung nào (như yêu cầu bộ nhớ, khóa API DO, IPv6 hoặc mạng riêng).
  • Cài đặt và cấu hình phần mềm, chẳng hạn như Apache, LAMP hoặc database .
  • Cài đặt DNS bắt buộc hoặc certificate SSL.

Các hướng dẫn phát triển phần mềm của ta hoạt động theo cách tương tự, cung cấp cho người đọc tất cả các yêu cầu mà họ cần từ trước, bao gồm cả yêu cầu cho môi trường phát triển.

Các yêu cầu chung cho các hướng dẫn phát triển phần mềm bao gồm:

  • Phần mềm local cần thiết, chẳng hạn như Git, Node.js, Python, Ruby hoặc Docker.
  • Các account user bổ sung như GitHub, Facebook, Twitter hoặc các dịch vụ khác mà người đọc của bạn cần .
  • Các hướng dẫn sẽ giúp người đọc bắt đầu dự án của họ, chẳng hạn như hoặc Cách cài đặt một dự án HTML .
  • Các bài báo khái niệm cung cấp thông tin cơ bản quan trọng mà người đọc có thể thấy hữu ích, chẳng hạn như Tìm hiểu DOM .

Ví dụ: một hướng dẫn về cách xây dựng và triển khai ứng dụng Node.js và triển khai nó lên server Ubuntu bằng Git có thể có các yêu cầu sau:

Yêu cầu

Để hoàn thành hướng dẫn này, bạn cần :

Bằng cách đọc các yêu cầu , người đọc của bạn biết chính xác những gì họ cần làm trước khi bắt đầu. Không có bất ngờ.

Khi bạn kiểm tra hướng dẫn của bạn , hãy đảm bảo bạn làm theo tất cả các hướng dẫn tiên quyết chính xác như đã viết, để mọi người sử dụng cùng một điểm xuất phát. Nếu bạn đã thay đổi một biến hoặc hoàn thành một bước tùy chọn từ một trong các yêu cầu , hãy nhớ lưu ý điều đó.

Bạn có thể xem các ví dụ về yêu cầu tốt cho:

Hãy cụ thể với các yêu cầu của bạn. Yêu cầu như "Quen thuộc với JavaScript" mà không có liên kết đến một cái gì đó cụ thể sẽ không cung cấp cho người đọc của bạn nhiều ngữ cảnh. Thay vào đó, hãy cân nhắc liệt kê các khái niệm cụ thể mà người đọc nên biết và cung cấp cho họ các tài nguyên giúp họ bắt kịp tốc độ để họ có thể hoàn thành hướng dẫn của bạn thành công.

Các bước

Phần Bước là các phần trong hướng dẫn của bạn, nơi bạn mô tả những gì người đọc cần làm. Một bước chứa các lệnh, danh sách mã và file , đồng thời cung cấp các giải thích không chỉ giải thích những gì cần làm mà còn giải thích tại sao bạn làm theo cách này.

Mỗi bước bắt đầu với tiêu đề cấp 2 và sử dụng mầm, là các từ -ing .

Hướng dẫn thủ tục nên bắt đầu mỗi tiêu đề bước bằng từ Bước và một số, theo sau là dấu gạch ngang:

Bước 1 - Tạo account user

Sau tiêu đề, hãy thêm một câu giới thiệu mô tả những gì người đọc sẽ làm trong mỗi bước và role của nó trong việc đạt được mục tiêu chung của hướng dẫn. Tập trung vào người đọc. Thay vì các cụm từ như “ Ta sẽ học” hoặc “Tôi sẽ giải thích”, hãy sử dụng các cụm từ như “Bạn sẽ xây dựng” hoặc “bạn sẽ tạo ra”.

Kết thúc mỗi bước bằng một câu chuyển tiếp mô tả những gì người đọc đã hoàn thành và nơi họ sẽ đi tiếp theo. Tránh lặp lại tiêu đề bước trong phần giới thiệu và chuyển tiếp này, đồng thời không bắt đầu hoặc kết thúc các bước bằng hướng dẫn, lệnh hoặc kết quả không có ngữ cảnh.

Lệnh trong các bước

Tất cả các lệnh mà người đọc phải chạy phải nằm trên dòng riêng của chúng trong khối mã của riêng chúng, và mỗi lệnh phải được đặt trước một mô tả giải thích lệnh đó làm gì. Sau lệnh, bạn nên cung cấp thêm chi tiết về lệnh, chẳng hạn như chức năng của các đối số và lý do tại sao trình đọc của bạn sử dụng chúng.

Thực thi lệnh sau để hiển thị nội dung của folder /home/ sammy , bao gồm tất cả các file ẩn:

  • ls -al /home/sammy

Lựa chọn -a hiển thị tất cả các file , kể cả những file bị ẩn và lựa chọn -l hiển thị một danh sách dài bao gồm dấu thời gian và kích thước file .

Bạn nên hiển thị kết quả của các lệnh và chương trình bằng cách sử dụng một khối mã riêng biệt, như trong ví dụ sau:

Chạy chương trình hello.js :

  • node hello.js

Bạn sẽ thấy kết quả của chương trình xuất hiện trên màn hình:

Output
Hello world! This is my first Node.js program!

Lưu ý khối kết quả có nhãn và được ngăn cách với lệnh bằng một số văn bản giải thích kết quả kết quả . Việc tách các lệnh khỏi kết quả giúp người đọc hiểu rõ hơn nơi lệnh kết thúc và kết quả bắt đầu.

Mở, tạo và xem file

Giống như các lệnh, luôn giới thiệu file hoặc tập lệnh bằng cách mô tả mục đích chung của nó, sau đó giải thích bất kỳ thay đổi nào mà người đọc sẽ thực hiện trong file . Nếu không có những giải thích này, người đọc sẽ không thể tùy chỉnh, cập nhật hoặc khắc phục sự cố về lâu dài.

Yêu cầu user tạo hoặc mở từng file một cách rõ ràng mà bạn sẽ sử dụng.

Trên các hướng dẫn nhắm đến đến user dòng lệnh, hãy hướng dẫn người đọc tạo và mở file bằng lệnh trên dòng của chính file đó:

Mở file /etc/hginx/config bằng lệnh sau:

  • nano /etc/nginx/sites-available/default

Ta sử dụng trình soạn thảo nano cho các hướng dẫn Ubuntu và Debian vì nó đã được cài đặt. Ta sử dụng vi trong các hướng dẫn cho CentOS và FreeBSD. Trong mọi trường hợp, tránh sử dụng thao tác touch để tạo file trống mới vì thay vào đó, người đọc của bạn có thể tạo file trực tiếp bằng editor .

Đối với các hướng dẫn mà người đọc không được mong đợi sử dụng giao diện dòng lệnh, chẳng hạn như hướng dẫn phát triển front-end, bạn có thể bỏ qua lệnh để mở file . Tuy nhiên, hãy đảm bảo cho người đọc biết file nào cần mở một cách rõ ràng:

Mở file src/App.js trong editor .

Người đọc phải luôn biết họ đang làm việc với file nào.

Khối mã

Nếu bạn đang yêu cầu người đọc viết mã, hãy làm theo cách tiếp cận tương tự cho các lệnh: giới thiệu khối mã với giải thích cấp cao về chức năng của nó. Sau đó, hiển thị mã, và sau đó gọi ra bất kỳ chi tiết quan trọng nào.

Đây là một ví dụ:

Tạo file hello.js trong editor của bạn:

  • nano hello.js

Thêm mã sau vào file sẽ in thông báo ra màn hình:

xin chào.js
console.log("Hello world!"); console.log("this is my first Node.js program!")

Hàm console.log nhận một chuỗi và in ra màn hình theo dòng riêng của nó.

Lưu ý danh sách mã có nhãn hiển thị rõ ràng tên file .

Đôi khi bạn sẽ mở một file và yêu cầu người đọc thay đổi điều gì đó cụ thể. Khi bạn thực hiện việc này, hãy hiển thị các phần có liên quan của file và sử dụng tô sáng để làm rõ những gì nên thay đổi:

Mở file /etc/nginx/sites-available/default trong editor :

  • nano /etc/nginx/sites-available/default

Thay đổi giá trị server_name thành domain của bạn:

/ etc / nginx / sites-available / default
server {     listen 80 default_server;     listen [::]:80 default_server ipv6only=on;      root /usr/share/nginx/html;     index index.html index.htm;      server_name your_domain; ...  }

Hướng dẫn định dạng và Markdown tùy chỉnh của DigitalOcean được thiết kế để giúp làm cho các hướng dẫn của ta dễ đọc nhất có thể. Hướng dẫn Docker Swarm này là một ví dụ điển hình về cách sử dụng Markdown tùy chỉnh của ta để phân biệt giữa các lệnh chạy trên một số server khác nhau, cũng như local .

Kết luận

Kết luận của hướng dẫn của bạn nên tóm tắt những gì người đọc đã hoàn thành khi làm theo hướng dẫn của bạn. Thay vì sử dụng các cụm từ như “ ta đã học cách làm”, hãy sử dụng các cụm từ như “bạn đã cấu hình” hoặc “bạn đã xây dựng”.

Kết luận cũng nên mô tả những gì người đọc có thể làm tiếp theo. Điều này có thể bao gồm mô tả về các trường hợp sử dụng hoặc tính năng mà người đọc có thể khám phá, liên kết đến các hướng dẫn DigitalOcean khác với cài đặt hoặc cấu hình bổ sung và tài liệu bên ngoài.

Một số ví dụ điển hình bao gồm kết luận của hướng dẫn LXD này, kết luận của hướng dẫn giám sát CPU này và kết luận của hướng dẫn Mosquitto này .

Định dạng

Hướng dẫn DigitalOcean được định dạng bằng ngôn ngữ đánh dấu Markdown. Daring Fireball xuất bản một hướng dẫn Markdown toàn diện nếu bạn không quen với nó. DigitalOcean cũng sử dụng một số Markdown tùy chỉnh . Ví dụ về Markdown tùy chỉnh của ta có trong các phần thích hợp bên dưới.

Tiêu đề

Mỗi phần trong các hướng dẫn của ta có một tiêu đề tương ứng: tiêu đề phải là tiêu đề H1; phần giới thiệu phải là một tiêu đề H3; các mục tiêu, yêu cầu , các bước và kết luận phải có tiêu đề H2. Bạn có thể thấy định dạng này trong các mẫu bài viết Markdown của ta .

Đối với hướng dẫn thủ tục, tiêu đề bước nên bao gồm số bước (số) theo sau là dấu gạch ngang em ( - ).

Tiêu đề bước cũng nên sử dụng mầm, là các từ -ing . Tiêu đề bước ví dụ là Bước 1 - Cài đặt Nginx .

Sử dụng tiêu đề H3 một cách tiết kiệm và tránh tiêu đề H4. Nếu bạn cần sử dụng tiêu đề phụ, hãy đảm bảo có hai hoặc nhiều tiêu đề của cấp đó trong phần đó của hướng dẫn. Ngoài ra, hãy cân nhắc thực hiện nhiều bước.

Định dạng mức dòng

Văn bản in đậm nên được sử dụng cho:

  • Văn bản GUI hiển thị
  • Tên server và tên user , như wordpress-1 hoặc sammy
  • Danh sách thuật ngữ
  • Nhấn mạnh khi thay đổi ngữ cảnh cho một lệnh, chẳng hạn như chuyển sang server hoặc user mới

Chỉ nên sử dụng chữ in nghiêng khi giới thiệu các thuật ngữ kỹ thuật. Ví dụ: server Nginx sẽ là bộ cân bằng tải của ta .

Định dạng mã nội dòng nên được sử dụng cho:

  • Tên lệnh, như unzip
  • Tên gói, như mysql-server
  • Các lệnh tùy chọn
  • Tên file và đường dẫn, như ~/.ssh/authorized_keys
  • URL mẫu, như http:// your_domain
  • Các cổng, như :3000
  • Các phím bấm, phải ở dạng CHỮ HOA TẤT CẢ và sử dụng biểu tượng dấu cộng, + , nếu các phím cần được nhấn đồng thời, như ENTER hoặc CTRL+C

Khối mã

Các khối mã nên được sử dụng cho:

  • Các lệnh mà người đọc cần thực hiện để hoàn thành hướng dẫn
  • Tệp và tập lệnh
  • Đầu ra terminal
  • Các cuộc đối thoại tương tác trong văn bản

Chỉ ra các đoạn trích và thiếu sót trong file bằng dấu chấm lửng ( … ):

/ etc / nginx / sites-available / default
server {     listen 80 default_server;     listen [::]:80 default_server ipv6only=on;      root /usr/share/nginx/html;     index index.html index.htm;      server_name your_domain; ...  }

Nếu hầu hết file có thể được giữ nguyên với cài đặt mặc định, tốt hơn là bạn nên chỉ hiển thị phần cần thay đổi.

Tiền tố khối mã

Không bao gồm dấu nhắc lệnh ( $ hoặc # ) trong khối mã. Thay vào đó, hãy sử dụng Markdown tùy chỉnh của DigitalOcean cho các lệnh của user không phải root, lệnh của user root và tiền tố tùy chỉnh, tương ứng:

```command sudo apt-get update ```  ```super_user adduser sammy ```  ```custom_prefix(mysql>) FLUSH PRIVILEGES; ```

Đây là cách các ví dụ trước trông như thế nào khi được hiển thị:

  • sudo apt-get update 
  • adduser sammy 
  • FLUSH PRIVILEGES;

Người đọc sẽ không thể vô tình chọn các ký tự nhắc khi bạn trình bày các lệnh theo cách này.

Nhãn khối mã

Markdown của DigitalOcean cũng bao gồm nhãn và nhãn phụ. Bạn có thể thêm nhãn vào các khối mã bằng cách thêm một dòng có [label Label text] hoặc [secondary_label Secondary label text] ở bất kỳ đâu trong khối.

Sử dụng nhãn để đánh dấu các khối mã chứa nội dung của file với tên file . Ví dụ: nếu bạn có một file có tên là app.js , hãy sử dụng [label app.js] để gắn nhãn cho khối mã:

```js [label app.js] console.log("Hello World!"); ```

Nhãn được hiển thị phía trên danh sách mã:

app.js
console.log("Hello World!");

Sử dụng nhãn phụ để đánh dấu terminal hoặc kết quả chương trình được in ra màn hình, như sau:

``` [secondary_label Output] Hello World! ```

Các nhãn phụ trông như thế này:

Output
Hello World!

Nhãn giúp người đọc hiểu những gì họ đang xem và cách nó phù hợp với bức tranh lớn hơn.

Màu môi trường khối mã

Đôi khi, bạn sẽ để trình đọc hoạt động trên nhiều máy tính, chẳng hạn như máy local và nhiều server của chúng. Sử dụng các màu khác nhau cho kết quả có thể giúp người đọc dễ theo dõi hơn. Markdown của DigitalOcean cho phép bạn tô màu nền của khối mã bằng cách thêm một dòng có [environment name ] vào bất kỳ vị trí nào trong khối. Các tùy chọn cho name là local , second , third , fourth và fifth .

Ví dụ: nếu bạn đang viết một hướng dẫn và bạn muốn hiển thị một lệnh sẽ được chạy local thay vì trên server , bạn có thể sử dụng [environment local] :

  • ssh root@your_server_ip

Đây là các ví dụ về lệnh server không phải chính, hữu ích cho các cài đặt nhiều server :

Sử dụng [environment second] trông giống như sau:

  • echo "Secondary server"

Sử dụng [environment third] trông giống như sau:

  • echo "Third server"

Sử dụng [environment fourth] trông giống như sau:

  • echo "Fourth server"

Và [environment fifth ] trông như thế này:

  • echo "Fifth server

Sử dụng những màu này trong hướng dẫn đa server hoặc đa môi trường.

Ghi chú và Cảnh báo

Trình phân tích cú pháp DigitalOcean Markdown cho phép các khối mã ghi chú và cảnh báo tùy chỉnh được sử dụng để hiển thị văn bản rất quan trọng.

Đây là ví dụ về Markdown của ghi chú và cảnh báo (đây là hình ảnh):

Ghi chú và Cảnh báo

Đây là kết quả được hiển thị:

Lưu ý: Đây là một lưu ý.

Cảnh báo: Đây là một cảnh báo.

Thông tin cụ thể về DigitalOcean

Chú thích [info] hữu ích khi thảo luận về các tính năng cụ thể của DigitalOcean.

Tính năng này dành riêng cho server của DigitalOcean.

Biến

Đánh dấu bất kỳ mục nào mà người đọc cần thay đổi, như URL mẫu hoặc các dòng đã sửa đổi trong file cấu hình. Bạn có thể làm điều này bằng cách bao quanh từ hoặc dòng với <^> Markdown tùy chỉnh của ta .

Lưu ý : Bạn không thể đánh dấu nhiều dòng với một cặp ký hiệu, vì vậy bạn cần đánh dấu từng dòng riêng lẻ.

Nếu bạn tham chiếu một biến trong ngữ cảnh mà bạn thường sử dụng định dạng in-line code , bạn nên sử dụng both styles . Đảm bảo hướng dẫn của bạn dễ tiếp cận nhất có thể bằng cách sử dụng ngôn ngữ như “được đánh dấu trong khối mã trước” thay vì “được đánh dấu màu đỏ ở trên”.

Tránh ngôn ngữ như "được đánh dấu bằng màu vàng", vì màu đánh dấu có thể thay đổi.

Hình ảnh và các tài sản khác

Hình ảnh có thể nhanh chóng minh họa một điểm hoặc cung cấp thêm thông tin làm rõ trong một bước. Sử dụng hình ảnh cho ảnh chụp màn hình của GUI, hội thoại tương tác và sơ đồ cài đặt server . Không sử dụng hình ảnh cho ảnh chụp màn hình của mã, file cấu hình, kết quả hoặc bất kỳ thứ gì có thể sao chép và paste vào bài viết.

Nếu bạn đưa hình ảnh vào hướng dẫn của bạn , hãy làm theo các nguyên tắc sau:

  • Bao gồm văn bản thay thế mô tả để người đọc sử dụng trình đọc màn hình có thể tin tưởng vào văn bản thay thế hơn là hình ảnh.
  • Sử dụng định dạng file .png .
  • Lưu trữ hình ảnh trên imgur .
  • Đặt hình ảnh với chiều cao càng ngắn càng tốt.

Nếu bạn tạo mô hình sơ đồ cho hướng dẫn của bạn , ta sẽ tạo sơ đồ theo phong cách DigitalOcean. Ta cũng sẽ tải tất cả hình ảnh lên server DigitalOcean tại thời điểm xuất bản.

Đây là một ví dụ về Markdown để đưa hình ảnh vào hướng dẫn của bạn:

![Alt text for screen readers](http://imgur.com/your_image_url)

Đôi khi, bạn cần người đọc có quyền truy cập vào file cấu hình quá dài để hiển thị trong phần chính của hướng dẫn. DigitalOcean sẽ lưu trữ file này trên server nội dung của ta . Bạn có thể sử dụng định dạng liên kết chuẩn để liên kết đến file .

Thuật ngữ

Các bài viết và hướng dẫn kỹ thuật sẽ sử dụng rất nhiều thuật ngữ và ta đã chuẩn hóa một số thuật ngữ và cách sử dụng từ.

User , Tên server và Miền

Tên user ví dụ mặc định của ta là sammy . Bạn cũng có thể chọn một cái gì đó mang tính mô tả nếu hữu ích, như webdav-kai hoặc nsd .

your_server là tên server mặc định, mặc dù bạn có thể cần chọn một cái gì đó mô tả hơn trong các cài đặt nhiều server , như django_replica_1 .

your_domain là domain mặc định. Đối với cài đặt nhiều server , bạn có thể chọn thông tin như tên domain chính-1.your_domain hoặc bản sao-1.your_domain . Mặc dù example.com là một domain hợp lệ cho tài liệu, việc sử dụng your_domain trong các hướng dẫn làm rõ ràng hơn rằng người đọc nên thay đổi domain trong các ví dụ.

Sử dụng đánh dấu khi sử dụng chúng trong các file cấu hình, mã và khối kết quả , như sau:

file cấu hình ví dụ
ip: your_server_ip domain: primary-1.your_domain

Điều này làm cho người đọc thấy rõ rằng có điều gì đó họ nên thay đổi.

Địa chỉ IP và URL

your_server_ip , với định dạng mã nội tuyến và đánh dấu biến, là cách mặc định để hiển thị địa chỉ IP. Bạn có thể hiển thị nhiều địa chỉ IP với các tên như primary_private_ip và replica_private_ip . Nếu bạn cần minh họa các địa chỉ IP thực tế hơn, hãy sử dụng địa chỉ ở một trong hai khối được dành riêng cho tài liệu theo RFC-5737 . Cụ thể, ta đề xuất 203.0.113.0/24 ví dụ địa chỉ công cộng và 198.51.100.0/24 ví dụ địa chỉ riêng tư.

Các URL mẫu có chứa một biến mà người đọc cần tùy chỉnh phải sử dụng định dạng mã với biến được đánh dấu. Ta mặc định sử dụng your_domain . như https:// your_domain :3000/simple/ hoặc http:// your_server_ip / . Tuy nhiên, các liên kết trực tiếp thay vào đó nên sử dụng kiểu liên kết Markdown tiêu chuẩn mà không có định dạng bổ sung.

Phần mềm

Sử dụng cách viết hoa của trang web chính thức của tên phần mềm của họ. Nếu trang web sản phẩm không nhất quán với cách viết hoa của chúng, hãy nhất quán trong một bài viết.

Liên kết đến trang chủ của phần mềm khi bạn lần đầu tiên đề cập đến phần mềm.

Cài đặt nhiều server

Để rõ ràng về kỹ thuật, hãy sử dụng thuật ngữ của dự án cho cài đặt nhiều server . Hãy rõ ràng rằng các điều khoản đến từ dự án. Ví dụ: “Dự án Django đề cập đến server root là server chính và server phụ là bản sao . Dự án MySQL đề cập đến server root như là bậc thầy và các server thứ cấp như slaver .”

Khi thảo luận về kiến trúc đa server một cách trừu tượng hơn, hãy sử dụng các thuật ngữ chính và bản sao hoặc trình quản lý và nhân viên .

Thực tiễn tốt nhất về kỹ thuật

Hướng dẫn hướng dẫn các phương pháp hay nhất về kỹ thuật của ta chứa nhiều hướng dẫn hơn sẽ giúp bạn tạo các hướng dẫn nhất quán, chất lượng giúp ích cho người đọc của ta .

Theo liên kết này để trở thành tác giả DigitalOcean .

Tags:

Các tin liên quan