チュートリアルガイドライン

私たちは、開発者がXRP Ledger上でのトランザクションやリクエストの仕組みを学ぶことができる、モジュール式のチュートリアルフレームワークを作成しています。開発者は、ビジネスソリューションについて学ぶためにモジュールを確認し、自身のアプリケーションでスクリプトを再利用することができます。

根拠

開発者は次の2つのことを求めています。

1. 自分のアプリケーションにコピー＆ペーストできるコードのサンプル。
2. 完全なAPIリファレンスのドキュメント。

コンセプトに関する情報は最小限としチュートリアルを完了するために必要な情報のみとしてください。背景やより深い理解のために、必要であれば、チュートリアルの最後にコンセプトに関するトピックへのリンクを提供してください。

チュートリアルプログラムは、マルコム・ノウルズが提唱する、社会人の学習を支援するための6つの前提に沿って構成されています。

1. 大人は、なぜ何かを学ぶ必要があるのかを知る必要があります。
2. 大人は、経験を積み重ねる必要があります。
3. 大人は、自分の学習に責任を感じる必要があります。
4. 大人は、トレーニングが当面の問題を解決してくれるなら、学ぶ準備が整っています。
5. 大人は、トレーニングが問題に焦点を当てたものであることを望みます。
6. 大人は、動機づけが内発的にもたらされるときに最もよく学びます。

さらに、ラルフ・スメドレーの「人は楽しいときに最もよく学ぶ」という言葉も付け加えておきましょう。軽い気持ちで学ぶと、学習者をリラックスさせることができ、教材が抵抗なく頭に入ってくるのです。

サンプルコード vs タスク vs コンセプト vs チュートリアル

これまで、異なるタイプのドキュメントが チュートリアル として表示されたり、境界線が曖昧なことがありました。ここでは、その違いを定義するのに役立ついくつかの比較を紹介します。

サンプルコード

サンプルコードとは、APIの機能を実装するためのベストプラクティスを示す、適切にコメントされたスニペットやアプリケーションのことです。サンプルコードはモジュール化されており、カスタマイズをほとんど必要とせず、再利用可能です。

サンプルコードは理想的です。なぜなら、上級者は通常、正式なチュートリアルがなくても、サンプルをスキャンしてすぐに使うことができるからです。また、他の人がチュートリアルの基礎として使うこともできます。サンプルコードの開発者は、自分の得意なことに集中することができ、テクニカルライターやサポート担当者は、サンプルを使って質の高いトレーニング資料を作成することができます。

タスク

タスクは、特定の目的を達成するためのステップバイステップの指示です。例えば、"Red Hat Linux Serverにrippledをインストールする"などです。タスクドキュメントはあまり教育的なものではありません。実装ごとに一度だけ実行されるタスクや、常におなじみのパターンに従うメンテナンスタスクが頻繁に記述されています。タスクはトラブルシューティングのガイダンスを示します。

コンセプト

コンセプトでは、API の要素やそれらがどのように動作するか、どのような場合にそれらを使用するかについて説明します。もしチュートリアルがプログラミングのタスクの前や途中に長い説明を必要とする場合、説明を新しいトピックに分けるか、既存のトピックにリンクして適切なコンテキストを設定する方法を検討してください。

例えば、3段落のコンテキストと1行のコードは、チュートリアルではなく、コンセプトとして扱うべきでしょう。

チュートリアル

チュートリアルは、機能を実装するためのベストプラクティスを示すサンプルコードから始まります。チュートリアルでは、コードの各ブロックの目的を説明しながら、開発のプロセスを段階的に進めていきます。

チュートリアルではさらに、ビジネス上の問題を解決するために、いくつかの機能を組み合わせます。チュートリアルでは、あるタスクを完了するための簡単な手順を説明します。そして、開発者がいくつかの異なるシナリオを試せるように修正を提案するかもしれません。チュートリアルは、ある限られた範囲の動作に焦点を当てているため、広範なトラブルシューティング情報を必要としないようにすべきです。

ユースケース

ユースケースでは、複数の機能を組み合わせて、ビジネス上の問題を解決する実用的なアプリケーションを作成する方法を説明します。ユースケースは、コンテキストを提供し、意思決定プロセスを支援し、実装の各ステップに適切なトピックへのリンクを提供します。

チュートリアルの構成要素

このセクションでは、XRPL.orgで使用されているチュートリアルモジュールの要素について説明します。

サンプルアプリケーション

XRPLチュートリアルのサンプルコードはモジュール式になっています。例えば、スクリプト1はテストアカウントの作成方法、XRP Ledgerへのアクセス方法、アカウント間でのXRP送金方法を示しています。それ以降のサンプルはスクリプト1の機能を再利用することができます。

ビジネス上の問題に対する実用的な解決策を示すために必要な、特定の最小限の関数コードを持つ新しいスクリプトを作成してください。サンプルは、ビジネスプロセスを説明するのに十分な動作を持つ逐次的なものでなければなりません。

たとえば、最初のNFTチュートリアルでは、NFTのミント、取得、バーンの方法を示します。次のチュートリアルでは、売りオファーの作成と受け入れ、買いオファーの作成と受け入れの方法を示します。

アプリケーションのUXは、トピックに関連するものでない限り、過度に重視しないでください。すべてのチュートリアルで、標準的な外観と操作感のCSSファイルを使用してください。

可能な限り、他のモジュールのコードを再利用してください。以前のモジュールの動作を変更する必要がある場合があります。関数名をオーバーロードするか、モジュールを修正して別の名前で保存してください。