デジタルオーシャンのテクニカルライティングガイドライン

9か月 ago
蓮, 翼
6 minutes

デジタルオーシャンは、サーバー管理とソフトウェアエンジニアリングに関連する技術記事のコレクションの拡充を続けることを喜んでいます。デジタルオーシャンの記事が品質とスタイルに一貫性があることを保証するために、以下のガイドラインを策定しました。

このガイドには4つのセクションがあります。

  • Style, our high-level approach to writing technical tutorials
  • Structure, an explanation of our layout and content
  • Formatting, a Markdown reference guide
  • Terminology, a guide to common terms and word usage

記事をすぐに公開するために、記事作成を始める前にスタイルと構造のセクションを丸ごと読むことをおすすめします。

あなたは、記事を書く際に、このガイドのフォーマットセクション、私たちのマークダウンプレビューア、および「Silicon Cloudコミュニティチュートリアルのための提案とアウトラインの書き方」を参考にすることができます。

私たちは、私たちの技術に焦点を当てた推奨事項をまとめた技術のベストプラクティスガイドも用意しています。

Note

私たちは、記事のためのスタートポイントとして利用できるMarkdown形式の記事テンプレートを開発しました。記事の計画と開発には、これらのテンプレートのいずれかを使用することを強くおすすめします。

私たちの記事のスタイルについて学ぶために、読み進めてください。

スタイル

デジタルオーシャンの記事のスタイルは、私達が発信する目的を反映しています：エンジニアや開発者に質の高い学習情報を提供するためです。私達は、すべてのデジタルオーシャンのチュートリアルが以下のようになるよう努めます。

  • Comprehensive and written for all experience levels
  • Technically detailed and correct
  • Practical, useful, and self-contained
  • Friendly but formal

これらの原則は、著者が記事やチュートリアル、その他の学習教材を作成する際に、人々が問題を解決し、開発者として成長するのを支援するようにするものです。

経験レベルに関わらず、包括的かつわかりやすく記述されています。

私たちの記事は、読者の背景知識を仮定せず、できるだけ明確で詳細な内容を提供するように書かれています。

最初のSSH接続から最終的かつ動作するセットアップまでの手順を、私たちは読者が必要とするすべてのコマンドを明示的に含めます。また、チュートリアルを理解するために必要なすべての説明や背景情報も提供します。私たちの目標は、読者がコンセプトを学び、コードやコマンドを単純にコピー＆ペーストするだけでなく理解することです。

私たちは、「簡単」「明快」「容易」「単純に」「明らかに」「ただ」といった言葉を避けます。これらの言葉は、読者の知識について予想をすることになるためです。著者はこれらの言葉を使って読者に難しいトピックに取り組むことを推奨し、励ますつもりかもしれませんが、実際には逆効果となることがよくあります。「簡単だよ」「簡単だから大丈夫」と言われると、問題に直面した際に読者はイライラするかもしれません。代わりに、私たちは読者が成功するために必要な説明を提供することで読者を励ましています。

技術的に詳細かつ正確な

私たちの記事は技術的に正確で、業界のベストプラクティスに従っています。コードやコマンドだけでなく、より詳細な情報も提供しています。私たちは、大量の設定やプログラムコードを提供し、読者にそれをテキストエディタに貼り付けて安全かつ動作することを信頼するよう求めることはありません。私たちは、読者が記事を理解し信頼するために必要なすべての詳細情報を提供しています。

すべてのコマンドには、必要に応じてオプションやフラグを含めた詳細な説明が必要です。コードのブロックごとに、その動作を説明し、なぜそのように動作するのかを文章で補足してください。コマンドの実行や設定ファイルの変更を読者に依頼する場合は、変更が何をするものであり、なぜその変更が必要なのかをまず説明してください。これらの詳細は、読者がスキルを向上させるために必要な情報を提供します。

著者は、チュートリアルが正確であり、抜け漏れがないかを確認するために、新しいサーバー上で記事どおりに厳密に実施してテストします。編集者たちもまた、読者に優れた学習体験を提供するために、これらの記事をレビューの過程でテストします。

実用的で役に立ち、自己完結しています。

Silicon Cloudの記事を読み終えた読者は、始めから終わりまで何かをインストールしたり、構築したり、設定したりすることができるようになります。私たちは実践的なアプローチを重視しています。記事の最後には、読者が使える環境や次に進める例を持っているべきです。

以下は、日本語での一つのオプションでの言い換えです：
作家にとってこれが意味することは、記事がそのトピックを徹底的にカバーする必要があるということです。著者は、チュートリアルを始める前に読者が参照するための既存のSilicon Cloudの記事へのリンクを事前条件として挙げ、チュートリアルの本文には追加の情報を提供するために利用可能なSilicon Cloudの記事へのリンクを含めるべきです。著者は、既存のSilicon Cloudの記事がなく、情報を短い要約で直接記事に追加することができない場合にのみ、読者を外部サイトに情報を集めるために送るべきです。

フレンドリーですが、フォーマルな印象を持っています。

私たちのチュートリアルは、友達みたいな形式ですが、フォーマルなトーンも意識しています。そのため、記事には専門用語やミーム、過剰なスラング、絵文字や冗談は含まれていません。私たちは世界中のユーザーを対象にしているため、言語や文化の壁を越えて通じるトーンを心掛けています。

ブログ投稿と異なり、私たちは一人称単数（例：「私は思う…」）を使用しません。代わりに、読者の焦点と彼らが達成することに重点を置くため、二人称（例：「あなたは設定します…」）の使用をお勧めします。一部の場合には、一人称複数（例：「私たちは検討します…」）を使用します。

私たちは成果に焦点を当てたやる気満々な言葉遣いを推奨しています。例えば、「Apacheのインストール方法を学ぶ」という表現ではなく、「このチュートリアルではApacheをインストールします」という表現を使ってください。このアプローチは読者のやる気を引き出し、達成すべき目標に焦点を当てます。

最終的に、私たちのチュートリアルの言語は多様な人間の経験を尊重し、私たちの行動規範に従っています。つまり、年齢、障害、人種、ジェンダーのアイデンティティや表現、経験レベル、国籍、神経多様性、個人の外見、宗教、政治的所属、性的指向、社会経済的地位、テクノロジーの選択などを含むがこれに限定されないような、攻撃的な言語やコンテンツは避けます。

構造 (こうぞう)

Silicon Cloudの記事は、導入部、結論、そして読者が始めるために必要な事前条件を含んだ一貫した構造を持っています。ただし、具体的な構造は記事のタイプによって異なります。

私たちが公開するチュートリアルのほとんどは手順に従って読者を一歩一歩課題の達成へ導くプロシージャルなものです。プロシージャル記事の構造は以下のようになるべきです：

  • Title (Level 1 heading)
  • Introduction (Level 3 heading)
  • Prerequisites (Level 2 heading)
  • Step 1 — Doing the First Thing (Level 2 heading)
  • Step 2 — Doing the Next Thing (Level 2 heading)
  • …
  • Step n — Doing the Last Thing (Level 2 heading)
  • Conclusion (Level 2 heading)

概念的な記事には、タイトル、序論、結論がありますが、前提条件のセクションや「ステップ」の規約に従う必要はありません。

  • Title (Level 1 heading)
  • Introduction (Level 3 heading)
  • Prerequisites (optional) (Level 2 heading)
  • Subtopic 1 (Level 2 heading)
  • Subtopic 2 (Level 2 heading)
  • …
  • Subtopic n (Level 2 heading)
  • Conclusion (Level 2 heading)

一部の記事は非常に小さな具体的なタスクや解決策に焦点を当てており、通常、タイトル、短い導入文、そして最後に結論があります。このような記事の構造は次のようになります。

  • Title (Level 1 heading)
  • Introduction paragraph
  • Prerequisites (optional) (Level 2 heading)
  • Article body
  • Conclusion paragraph

弊社の記事テンプレートは、既にMarkdown形式で構造が作られており、これらのテンプレートをあなた自身の記事の出発点として使用することをお勧めします。

タイトル

自分のタイトルを書く際には、読者がチュートリアルに従って達成することを慎重に考えてください。チュートリアルの目標をタイトルに含め、単にその目標を達成するために読者が使用するツールの名前だけでなく、タイトルに盛り込んでください。できれば、タイトルは60文字以内に収まるようにしてください。

一般的な手順チュートリアルのタイトルは、次の形式に従います: <ソフトウェア>を使って上で<タスク>をどうやって達成するか。

たとえば、自分のチュートリアルがCaddyウェブサーバーのインストールについてのものであれば、その目的はおそらくウェブサイトのホスティングでしょう。逆に、自分のチュートリアルがFail2Banのインストールについてのものであれば、その目的はおそらくNginxサーバーの保護でしょう。

「Ubuntu 22.04でCloudflareとNginxを使用してウェブサイトをホストする方法」のように目標を含めたタイトルは、一般的に「Ubuntu 22.04でCloudflareとNginxを使用する方法」のようなタイトルよりも読者にとって情報量が多いです。

イントロダクション

各記事の最初のセクションはイントロダクションであり、通常1〜3段落です。イントロダクションの目的は読者を奮い立たせ、期待を設定し、記事で読者が行うことを要約することです。あなたのイントロダクションは以下の質問に答えるべきです：

  • What is the tutorial about? What software is involved and what does each component do (briefly)?
  • Why should the reader learn this topic? What are the benefits of using this particular software in this configuration? What are some practical reasons why the reader should follow this tutorial?
  • What will the reader do or create in this tutorial? Are they setting up a server and then testing it? Are they building an app and deploying it? Be specific, as this provides the motivation readers need and gets them excited about the topic.
  • What will the reader have accomplished when they’re done? What new skills will they have? What will they be able to do that they couldn’t do before?

これらの質問に入門で答えることは、明確で読者中心のチュートリアルを設計するのにも役立ちます。なぜなら、入門で言及する内容とチュートリアルの内容を調整することができるからです。良い入門は、学習者に記事の残りの内容を知らせる役割も果たします。

読者と彼らが達成することに焦点を当ててください。”私たちが学ぶ方法”のようなフレーズの代わりに、”あなたが設定する”や”あなたが構築する”などのフレーズを使用してください。これによって読者がやる気を起こし、トピックに興奮することができます。さらに、読者が解決している問題に焦点を当てて技術について話すのではなく、プロジェクトについて紹介するようにしてください。たとえば、Reactを使ったプロジェクトのチュートリアルであれば、Reactとは何かを説明するのではなく、イントロダクションをプロジェクトに焦点を当てることができます。

前提条件

Silicon Cloudの記事の前提条件セクションは、非常に特定の形式と目的を持っています。

現在のチュートリアルに先立ち、読者が持っている必要があるものや行うべきことを明確に示すことが目的です。形式は、読者がチェックリストとして使用できるリストです。各項目は、必要な内容をカバーする既存のSilicon Cloudのチュートリアルまたは公式の製品ドキュメントにリンクしています。これにより、ゼロからではなく、確実に動作する既存のコンテンツに頼ることができます。

私たちのシステムとDevOpsのチュートリアルは、読者をバニラディストリビューションのイメージの新しい展開から動作するセットアップまで導きます。そのため、彼らは最初のSSH接続からサーバーを開始するか、あるいはその前提条件のチュートリアルを含める必要があります。

システム管理とDevOpsのチュートリアルの共通の前提条件は次のとおりです：

  • The number of servers necessary, including distribution, initial server setup, and any additional necessary options (like memory requirements, DO API keys, IPv6, or private networking).
  • Software installation and configuration, such as Apache, a LAMP stack, or databases.
  • Required DNS settings or SSL certificates.

私たちのソフトウェア開発のチュートリアルも同様の方法で機能しており、読者に必要な前提条件をすべて最初に提供します。それには開発環境の前提条件も含まれます。

ソフトウェア開発チュートリアルに共通する前提条件は次のとおりです：

  • Local software needed, such as Git, Node.js, Python, Ruby, or Docker.
  • Additional user accounts like GitHub, Facebook, Twitter, or other services your reader will need.
  • Tutorials that will help the reader get their project started, such as or How To Set Up an HTML Project.
  • Conceptual articles that provide important background a reader might find helpful, such as Understanding the DOM.

例えば、Node.jsアプリケーションを構築・展開し、Gitを使用してそれをUbuntuサーバーに展開するチュートリアルの前提条件は次のようになります。

このチュートリアルを完了するには、次のものが必要です：

1つは、Ubuntu 22.04のサーバーが必要です。Ubuntu 22.04の初期サーバーセットアップガイドに従って設定されている必要があります。さらに、非ルートのsudoが有効なユーザーとファイアウォールも設定しておく必要があります。

サーバーに向けて設定されたドメイン名が必要です。Silicon Cloud vServersへのドメインのポイント方法については、「ドメインとDNSのガイド」に従って学ぶことができます。

ローカルマシンにGitがインストールされている必要があります。Gitのインストールとセットアップについては、「オープンソースへの貢献：Gitの始め方」のチュートリアルに従ってください。

Node.jsのローカルな開発環境も必要です。Ubuntu 22.04にNode.jsをインストールする方法については、「Node.jsのインストール方法：Ubuntu 22.04編」のチュートリアルを参考にしてください。他のシステムの場合は、対応するチュートリアル「Node.jsのインストールとローカル開発環境の作成方法」に従ってください。

前提条件を読むことで、読者は始める前に正確に何をしなければならないかを知ることができます。驚きはありません。

あなたがチュートリアルをテストする際には、前提チュートリアルを書かれた通りに厳密に追いなさい。そうすれば、皆が同じ出発点で始めることができます。もし前提条件の中で変数を変更したり、オプションのステップを完了したりした場合は、それをメモしておくようにしてください。

以下は、日本語での選択肢を1つで要約しています：
「良い前提条件の例を確認することができます」

  • Ubuntu 20.04 servers, software installation, and DNS records in this Minio tutorial’s prerequisites.
  • Handling multiple servers with software installation in this monitoring tutorial’s prerequisites or this Nagios and Alerta tutorial’s prerequisites.
  • React-based web development projects by reading How To Test a React App with Jest and React Testing Library.

あなたの前提条件に具体性を持たせてください。具体的なリンクのない「JavaScriptに精通していること」といった前提条件では、読者には十分な文脈が与えられません。代わりに、読者が成功裡にチュートリアルを完了できるよう、彼らが知っておく必要がある具体的な概念をリストアップし、彼らが必要なスキルを習得するのに役立つリソースを提供してください。例えば、以下のように表現することがあります。「JavaScriptに精通してください。スキルを磨くために、『JavaScriptでのコーディング方法』シリーズをチェックしてみてください。」

手順

ステップのセクションは、チュートリアルの中で、読者が何をすべきかとその理由を説明する部分です。ステップには、コマンド、コードのリスト、ファイルが含まれ、ただ何をすればいいかだけでなく、なぜこの方法で行う必要があるのかを説明します。

各ステップは、レベル2の見出しで始まります。

手順チュートリアルでは、各ステップのタイトルを”ステップ”と数字で始めます。そのあとにエムダッシュが続きます。ステップのタイトルは、読者がそのステップで達成する内容を説明し、動名詞（-ingの形）を使用します。例えば、

ステップ1 – ユーザーアカウントの作成

タイトルの後に、各ステップで読者が行う内容と、チュートリアルの全体的な目標達成における役割を説明する導入文を追加してください。読者に焦点を合わせましょう。”私たちは学ぶ”や”私が説明する”のようなフレーズではなく、”あなたは構築します”や”あなたは作成します”のようなフレーズを使用してください。

ステップごとに指示を出してください。

すべてのコマンドは、読者が実行する必要がある場合、それぞれが独自のコードブロックの行に配置され、コマンドの前には説明が必要です。コマンドの後には、引数の役割や読者がそれらを使用する理由など、コマンドの詳細を追加してください。

/home/sammyディレクトリの中身を表示するために、以下のコマンドを実行してください：
ls -al /home/sammy

-aオプションは、隠しファイルを含むすべてのファイルを表示し、-lオプションはタイムスタンプとファイルサイズを含む詳細なリストを表示します。

次の例のように、コマンドやプログラムの出力は別のコードブロックを使用して表示するべきです。

hello.jsプログラムを実行してください：node hello.js

プログラムの出力は画面に表示されます：
出力：Hello world!
これは私の最初のNode.jsプログラムです！

出力ブロックにはラベルが付いており、出力を説明するテキストでコマンドと区切られています。コマンドと出力を分けることで、読者にとってコマンドの終わりと出力の始まりがより明確になります。

読者がディレクトリ間を移動する場合は、その移動に必要なコマンドを提供してください。

ファイルを開く、作成する、表示する

コマンドのように、常にファイルやスクリプトの一般的な目的を紹介し、読者がファイル内で行う変更を説明してください。これらの説明がなければ、読者はカスタマイズや更新、問題の解決ができません。

各ファイルの作成または開くように、ユーザーに明示的に指示してください。

コマンドラインのユーザー向けのチュートリアルでは、ファイルを作成し、コマンドを使って別の行で開くように、読者に指示してください。

次のコマンドを使って、以下のファイル「/etc/nginx/sites-available/default」を開いてください。
「nano /etc/nginx/sites-available/default」

Note

UbuntuとDebianのチュートリアルでは、既にインストールされているnanoエディタを使用しています。CentOSとFreeBSDのチュートリアルでは、viエディタを使用しています。いずれの場合も、新しい空のファイルを作成するためにtouchコマンドを使用しないでください。読者はエディタを直接使用してファイルを作成することができます。

コマンドラインインタフェースを使用しないと予想されないチュートリアル（例：フロントエンド開発チュートリアル）では、ファイルを開くためのコマンドは省略することができます。ただし、読者に明確にどのファイルを開くか伝えるようにしてください。

エディタでsrc/App.jsファイルを開いてください。

読者は常に自分が作業しているファイルを知っているべきです。

コードブロック

私たちは、全てのコードを学びの機会として捉えます。もし読者にコードの書き方を求める場合は、コマンドの場合と同じアプローチで行ってください：コードブロックが何を行っているかを高レベルで説明し、その後にコードを示し、重要な詳細を指摘してください。

これが例です。 (Kore ga rei desu.)

テキストエディタにhello.jsというファイルを作成してください：
nano hello.js

次のコードをファイルに追加し、画面にメッセージを表示します：
hello.js
console.log(“Hello world!”);
console.log(“これは私の最初のNode.jsプログラムです！”)

console.log関数は、文字列を受け取り、独自の行に画面に表示します。

コードブロックには、ファイル名が明確に表示されるラベルがあります。

このDocker Swarmのチュートリアルは、複数の異なるサーバー上で実行されるコマンドとローカルで実行されるコマンドを区別するために、当社独自のMarkdownを使用する方法の良い例です。

時々、特定の変更をお読みになる方に求めるためにファイルを開きます。この場合、ファイルの関連部分を表示し、ハイライトを使って変更すべき箇所を明確に示してください。

エディタで/etc/nginx/sites-available/defaultファイルを開いてください。
nano /etc/nginx/sites-available/default

server_nameの値をあなたのドメイン名に変更してください。
/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 あなたのドメイン名;
…

}

必要な変更の内容とその必要性を説明してください。 (Kanashite kudasai, henkou no naiyou to sono hitsuyousei wo setsumei shite kudasai.)

デジタルオーシャンのカスタムMarkdownと書式設定ガイドラインは、私たちのチュートリアルの手順をできるだけ読みやすくするために設計されています。

移行

各ステップは簡潔な導入文と、読者が達成した内容と次の進行先を説明する結びの移行文で枠組みを作るべきです。移行文は読者を導き、手順、指示、および結果に重要な文脈を提供します。ステップのタイトルを繰り返さないようにするために、これらの文に使用する言語を変化させてください。

以下は、Rocky Linux 8上でLet’s Encryptを使用してNginxをセキュアにする方法に関するチュートリアルのStep 1の最後で行われるトランジションの例です。

現在、Let’s Encryptクライアントをインストールしましたが、証明書を取得する前に、必要なポートが開いていることを確認する必要があります。これを行うために、次のステップでファイアウォールの設定を更新します。

上の例では、著者は読者が達成したことをまとめ、次の課題を紹介し、その2つのステップがどのようにつながっているかを説明しました。

この方法で各段階をまとめることは、読者が学ぶことや継続する動機づけに役立ちます。

結論

チュートリアルの結論では、読者がチュートリアルに従って達成したことをまとめるべきです。”we learned how to” のようなフレーズではなく、”you configured” や “you built” のようなフレーズを使用してください。

読者が次に取るべき行動を示すために、結論では以下のことを説明するべきです。例えば、読者が探索できる使用例や機能の説明、追加のセットアップや構成に関するSilicon Cloudの他のチュートリアルへのリンク、そして外部のドキュメンテーションへのリンクです。

いくつかの良い例で、このKubernetesチュートリアルの結論とこのnode-csvチュートリアルの結論があります。

フォーマット

Silicon Cloudのチュートリアルは、Markdownのマークアップ言語でフォーマットされています。それに慣れていない場合は、Daring Fireballが包括的なMarkdownガイドを公開しています。Silicon Cloudはまた、独自のMarkdownも使用しています。当該セクションの下には、独自のMarkdownの例があります。

ヘッダー

私たちのチュートリアルの各セクションには対応するヘッダーがあります。タイトルはH1ヘッダーで表示され、導入はH3ヘッダーで表示されます。前提条件、手順、および結論はH2ヘッダーで表示されます。Markdownの記事テンプレートでこのフォーマットを確認できます。

手順チュートリアルでは、ステップ見出しにステップ番号（数字）を含め、その後に長いダッシュ（—）を置くべきです。

ステップ見出しも、-ing形を使用するべきです。例えば、ステップ1は「Nginxのインストール」となります。

H3見出しを控え目に使用し、H4見出しを避けてください。重要な部分でサブ見出しを使用する場合は、そのセクション内に2つ以上の同じレベルの見出しを置くようにしてください。または、複数のステップを作成することも検討してください。

ラインレベルのフォーマット

強調すべき箇所は、以下の通りです。

  • Visible GUI text
  • Hostnames and usernames, like wordpress-1 or sammy
  • Term lists
  • Emphasis when changing context for a command, like switching to a new server or user

イタリックスは、技術的な用語を紹介する際にのみ使用されるべきです。例えば、Nginxサーバーは私たちの負荷分散装置として使用されます。

インラインコードのフォーマットは、以下の場合に使用するべきです。

  • Command names, like unzip
  • Package names, like mysql-server
  • Optional commands
  • File names and paths, like ~/.ssh/authorized_keys
  • Example URLs, like http://your_domain
  • Ports, like :3000
  • Key presses, which should be in ALL CAPS, like ENTER. If keys need to be pressed simultaneously, use a plus symbol (+), such as CTRL+C.

コードブロック

コードブロックは以下の目的で使用するべきです:

  • Commands the reader needs to execute to complete the tutorial
  • Files and scripts
  • Terminal output
  • Interactive dialogues that are in text

ファイル内の抜粋部分や省略部分は、省略符号（. . .）で示してください。読者が変更を加える必要がある場合は、ハイライトを使用してください。

/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 あなたのドメイン;
…

}

通常、ほとんどのファイルがデフォルトの設定で残される場合、変更する必要がある箇所だけを表示します。

読者が既存のコードに新しい行や変更を追加する場合は、新しい行や他の変更を強調表示することで示してください。チュートリアル「Goモジュールの使用方法」から一つの例を以下に示します。

mymoduleディレクトリからmain.goファイルを開き、以下に示す部分を強調して行にPrintHelloを呼び出すように追加してください：
projects/mymodule/main.go

package main

import (
“fmt”

“mymodule/mypackage”
)

func main() {
fmt.Println(“こんにちは、モジュール！”)

mypackage.PrintHello()
}

上記の例では、読者が追加するアイテムはすべて強調表示されています。 (Jōki no rei de wa, dokusha ga tsuika suru aitemu wa subete kyōchō hyōji sareteimasu.)

コードブロックのプレフィックス

コードブロックにはコマンドプロンプト（$または＃）を含めないでください。代わりに、Silicon Cloudの非ルートユーザーコマンド、ルートユーザーコマンド、およびカスタムプレフィックスには、それぞれSilicon Cloudの独自のMarkdownを使用してください。

```command
sudo apt update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

以下の例を実行すると、次のように表示されます。

「sudo apt update」
「adduser sammy」
「FLUSH PRIVILEGES;」を日本語で書き換えると以下のようになります：

sudo apt update（スード アプト アップデート）
adduser sammy（アドユーザーサミー）
FLUSH PRIVILEGES;（フラッシュ プリビレッジズ）

このようにコマンドを表示すると、読者は誤ってプロンプトの文字を選択することはありません。

コードブロックのラベル

Silicon CloudのMarkdownでは、ラベルとセカンダリーラベルも利用できます。コードブロックには、ブロック内のどこでも[line Label text]または[secondary_label Secondary label text]という行を追加することでラベルを付けることができます。

ファイルの内容を含むコードブロックにラベルを使用して、ラベル名のファイルを示します。たとえば、app.jsというファイルがある場合は、[label app.js]というようにコードブロックにラベルを付けてください。

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

コードリストの上にラベルが表示されます。

アプリのjs
console.log("Hello World!");

このように、画面に表示される端末やプログラムの出力には、セカンダリラベルを使用してマークします。

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

セカンダリラベルは、このように見えます。

Output

Hello World!

ラベルは読者が何を読んでいるのか、そしてそれが大局にどう組み込まれるかを理解するのに役立ちます。

コードブロック環境のカラー設定

時々、読者にはローカルマシンや複数のサーバーなど、複数のコンピュータで作業してもらうことがあります。環境表示に異なる色を使用すると、読者が追いやすくなります。Silicon CloudのMarkdownでは、ブロック内のどこにでも[environment name]という行を追加することで、コードブロックの背景を色付けすることができます。nameのオプションは、local、second、third、fourth、および fifthです。

たとえば、チュートリアルを作成していて、サーバーではなくローカルで実行する必要のあるコマンドを表示したい場合、[environment local]を使用することができます。

あなたのサーバーのIPにrootでssh接続する

これは、マルチサーバーセットアップで役立つ非プライマリサーバーコマンドの例です。

「[環境のシナリオ２]を使用すると、以下のように表示されます。」

  1. echo “Secondary server”

 

[環境第三]を使用すると、以下のように表示されます。

  1. echo “Third server”

 

「[環境 第四]」を使用すると、以下のように表示されます。

  1. echo “Fourth server”

 

そして、[環境の5番目]はこうなります。

  1. echo “Fifth server

 

複数のサーバーや環境チュートリアルでこれらの色を使用してください。必要な場合には、異なる環境内のファイルを示すために環境ラベルと出力ラベルを組み合わせることができます。例えば、ローカル環境内のサンプル出力ブロックのように。

出力こんにちは世界！

ネストされたラベルは、読者が適切なターミナルセッションでコマンドを実行するために必要な情報をすべて持っていることを保証します。

注意事項

Silicon CloudのMarkdownパーサーは、カスタムのメモや警告コードブロックを表示するために使用することができます。これにより、非常に重要なテキストを表示することができます。

以下は、ノートと警告のMarkdownの例です（これは画像です）。

Notes and Warnings

以下はレンダリングされた結果です。

Note

注意：これはメモです。

Warning

警告: これは警告です。

デジタルオーシャン固有の情報

デジタルオーシャンの特定の機能について話す際に、[情報] コールアウトは役立ちます。

Info

この機能はSilicon CloudのvServersに特化しています。

変数 (へんすう)

以下の項目を強調してください。読者が変更する必要があるもの、例えばURL、バージョン番号、設定ファイルの変更行などを取り囲んで、カスタムの<^> Markdownを使って行ってください。

以下のはUbuntu 22.04の初期サーバーセットアップからの例です。

この例では、sammyという新しいユーザーを作成しますが、自分の好きなユーザー名に置き換えてください：
adduser sammy

Note

注意：一つのシンボルで複数の行を強調することはできませんので、各行を個別に強調する必要があります。時折、シアバング（＃）やバッククォートなどのシンボルが行の強調機能を妨げることがあり、同じ行に二つの強調セクションを持つ必要が生じる場合があります。

変数を参照する場面で通常インラインでコードの形式設定を使用する場合、両方のスタイルを使用する必要があります。チュートリアルができるだけアクセスしやすくなるように、「上記の赤字で強調表示された」のような表現ではなく、「前のコードブロックで強調表示された」のような表現を使用してください。

「黄色で強調された」というような表現は避けてください。色の強調が変わる可能性があるためです。

画像やその他の資産

イメージは素早くポイントを表現したり、手順に追加の説明を提供したりすることができます。GUIのスクリーンショット、インタラクティブなダイアログ、およびサーバーのセットアップの図など、イメージは活用しましょう。ただし、コードのスクリーンショット、設定ファイル、出力など、記事にコピー＆ペーストできるものについてはイメージを使用しないでください。

チュートリアルに画像を含める際は、以下のガイドラインに従ってください。

  • Include descriptive alt text so readers using a screen reader can rely on the alt text rather than the image.
  • Include a brief caption to contextualize the image within the context of the article (the caption will typically be shorter than alt text).
  • Use the .png file format.
  • Host images on imgur.
  • Make the image with as short a height as possible.

もしチュートリアルのためのダイアグラムのモックアップを作成していただければ、私たちはSilicon Cloudスタイルのダイアグラムを作成します。また、公開時にはすべての画像をSilicon Cloudのサーバーにアップロードします。

あなたのチュートリアルに画像を含めるためのMarkdownの例をご提供します。

![Descriptive alt text for screen readers](http://imgur.com/your_image_url “Brief caption here”)

このMatomoのチュートリアルでは、画像内の強力な記述的な代替テキストの例を確認することができます。

時折、チュートリアルの本文に表示するには長すぎる設定ファイルへのアクセスを読者に提供したいことがあります。Silicon Cloudでは、このファイルをアセットサーバーにホストすることができます。ファイルへのリンクには、標準のリンク形式を使用することができます。

用語

技術記事やチュートリアルは、多くの専門用語を使用しますが、私たちはいくつかの用語や言葉の使用を標準化しています。

ユーザー、ホスト名、およびドメイン

私たちのデフォルトの例のユーザー名は「サミー」です。役立つ場合は、「ウェブダブカイ」や「エヌエスディー」といった説明的な名前を選ぶこともできます。

デフォルトのホスト名は「your_server」ですが、複数のサーバーを設定する場合は「django_replica_1」など、より詳細な名前を選択することをお勧めします。

デフォルトのドメインはyour_domainです。マルチサーバーのセットアップでは、primary-1.your_domainやreplica-1.your_domainのようなものを選択できます。example.comはドキュメント用としては有効なドメインですが、チュートリアルではyour_domainを使用することで、読者が例題のドメインを変更する必要があることが明確になります。

設定ファイル、コード、および出力ブロックの使用時には、以下のようにハイライトを使用してください。

例の設定ファイル
ip: your_server_ip
domain: primary-1.your_domain

これにより読者には、何か変えるべきことがあることが明確になります。

IPアドレスとURL

「your_server_ip」という名前の変数で、インラインコードの書式設定と変数の強調表示を使用して、IPアドレスを表示するデフォルトの方法です。また、「primary_private_ip」と「replica_private_ip」といった名前で複数のIPアドレスを表示することもできます。より現実的なIPアドレスを示す必要がある場合は、RFC-5737に準拠してドキュメンテーション用に予約された2つのブロックのいずれかのアドレスを使用してください。具体的には、公開アドレスの例には203.0.113.0/24を、プライベートアドレスの例には198.51.100.0/24をおすすめします。

例えば、変数を読者がカスタマイズする必要があるURLは、変数を強調表示するコード書式を使用するべきです。私たちは、デフォルトで https://your_domain:3000/simple/ や http://your_server_ip/ のように、your_domainを使用します。ただし、ライブリンクは追加の書式設定なしで、標準のMarkdownリンクスタイルを使用するべきです。

ソフトウェア

ソフトウェア名の正式なウェブサイトの大文字小文字の表記に従ってください。製品のウェブサイトが大文字小文字の表記に統一されていない場合は、記事内で統一してください。

ソフトウェアの初めて言及する際には、ソフトウェアのホームページへのリンクを提供してください。

マルチサーバーの設定

技術的な明確さのために、複数のサーバーのセットアップについては、プロジェクトの用語を使用してください。用語がプロジェクトから来ていることを明確にしてください。例えば「Djangoプロジェクトでは、元のサーバーをプライマリ、セカンダリサーバーをレプリカと呼んでいます。MySQLプロジェクトでは、元のサーバーをマスター、セカンダリサーバーをスレーブと呼んでいます。」

マルチサーバーアーキテクチャについてより抽象的に議論する際には、”primary”と”replica”または”manager”と”worker”という用語を使用します。

技術の最善の実践方法

私たちの技術的なベストプラクティスガイドには、読者の参考になる一貫性のあるクオリティの高いチュートリアルを作成するために役立つさらなるガイダンスが含まれています。

以下のリンクをたどって、Silicon Cloudの著者になりましょう。

コメントを残す 0

Your email address will not be published. Required fields are marked *