mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-24 13:45:49 +00:00
Information Architecture v3 (#1934)
* Update look up escrows to remove redundant info about lookups via sender/destination. Modify cancel expired escrow for brevity. * Cancel escrow: fix notes * Add draft of updated cancel-escrow.js. * Update intro to escrows. * Add Escrow Tutorial * Minor corrections * Fix headings, add HTML * Update escrow docs This commit re-createsf205a92db2with some adjustments: - Omit the accidentally-created dir full of junk - Fix some typos and one mistake in the Escrow limitations section - Add a table to the EscrowCreate ref to clarify valid combos of fields. * Concept info from send-a-time-held-escrow added to escrow.md * IA: Move "Consensus Network" files This re-creates some work from the original commit56fffe0b9f* Rewrite escrows article (re-created) This commit re-creates relevant work from the following commits:9a4a588f2bUpdate escrow.md context infoe1b017dc83Remove references to using escrow for interledger payments. * IA: Move "XRPL servers" files This re-creates some work from original commit7611979abf* IA: move "production readiness" files. Re-creates work from the following commit:692438693aMove tutorials to concepts * New intro articles Original commit:56fffe0b9f* IA: Reorg account concepts Re-creates some work from original commit56fffe0b9f* IA: reorg transaction concepts Original commits:9d4eff9940WIP - reorg accounts7611979abfWIP dir. reorg * IA: reorg consensus concepts Original commit:56fffe0b9f* IA: Reorg ledger docs Original commit:56fffe0b9f- Rephrased some details of the section * IA: rename issuing/operational addresses page Original commit:56fffe0b9f* Moving use cases * Fleshing out Use Cases Note, the dactyl-config.yml file has not been fully updated. * Clean up checks conceptual info. * Remove redundant checks use case section Original commit:3c29e9c05e* IA: move Dex under tokens Original commit:d08b3ba7d7* Touch up stablecoin issuer use case (#1856) * Consolidate stablecoin use case * Stablecoin issuer: cleanup progress through sending * Stablecoin issuer: reorg second half (Note: the dactyl-config.yml is not fully reconciled yet) * Move rippled and clio tutorials into infrastructure * Remove link to checks amendement. * Add note to account_objects.md about commandline interface type field. * Merge expiration case with lifecycle section. * Interoperability Use Cases * Add graphics to intro * Move escrow use cases to dedicated page. * Update use case page intros and corresponding concept info. * Clarify meaning of direct XRP payments. * Intro link updates * Payment use cases * Remove some unnecessary links in transactions section Original commit:e6fcf4a4dc* Link cleanup in Tokens section Original commit:9588dd5e70* Touch up 'Configure Peering' section Original commit:fc8f0990b8* Clean up links in accounts section Original commit:3da5fde7a8* Add NFT mkt use case * p2p payments: edits to Wallets * Clean up payments use cases * Refine history description * IA: use case cleanup * IA: reconcile servers, ledgers sections * IA: reconcile payment types, tx, tokens * IA: reconcile accounts section * IA: reconcile infra * IA: Fix most broken links * Full Docs Index: omit from sidebar * IA: fix up most broken links * fix Absolute path link to internal content * Quick updates to Software Ecosystem * Remove some absolute links to internal resources * Fix remaining broken links in JA target * Contributing: tweak formatting * Tutorials: fix some minor issues * remove interop use cases * remove intro image and personal references to dennis * alphabetize-transaction-nav * Remove unused files * Add QS escrow tutorials * IA: move ledgers, consensus protocol files around * IA: update nav for new page hierarchy * reordering of topics under new networks and servers top-nav * Move "Naming" to "What is XRP?" * Update dactyl-config.yml Remove xrp.md from the TOC. * Update list-xrp-as-an-exchange.md Update link to what-is-xrp * Update list-xrp-as-an-exchange.ja.md Change link to what-is-xrp * Update currency-formats.md Change link to what-is-xrp * Update currency-formats.ja.md Change link to what-is-xrp * Update cancel-an-expired-escrow.md Change link to what-is-xrp * Update paymentchannelfund.md Change link to what-is-xml * Update look-up-escrows.md Change link to what-is-xrp * Update tokens.md change link to what-is-xrp * Update use-payment-channels.md * Update send-a-time-held-escrow.md Update link to what-is-xml * fix broken links * Update parallel-networks.md Change link to what-is-xml * Update parallel-networks.ja.md * Update invariant-checking.md Remove link to xrp.html * Update invariant-checking.ja.md Remove link to xrp.html * Update transaction-cost.md Change link to what-is-xrp * Update transaction-cost.ja.md Change link to what-is-xrp * Update send-a-conditionally-held-escrow.md Change link to what-is-xrp * Update stablecoin-issuer.md Change link to what-is-xrp * Update tokens.ja.md Change link to what-is-xml * Update autobridging.ja.md Change link to what-is-xrp * Update currency-formats.md update text * reorganize infrastructure nav section * Update currency-formats.md Try removing link altogether. * Update currency-formats.ja.md Remove link to what-is-xrp.html * move commandline usage topic to infrastructure * initial intro rewrite * minor update to language * IA.v3: rm Production Readiness * Delete xrp.md * Update xrp link in snippet * Add redirect for old xrp.html URL * Small edits to 'What is XRP?' article * Add missing imgs * XRP - copy edit per @DennisDawson * restructure tutorials nav and pages * fix broken links * more broken link fixes * Algo trading: 1st draft * Algo trading: notes on taxes * Algo trading: edits per review * algo trading: fix broken link * Ledger structure: rewrite for accuracy and clarity * Update links to removed 'tree format' header * Ledger Structure: Update diagrams * Re-gen CSS for ledger structure changes * Ledger structure: edits per review * IA.v3: fix broken NFT links introduced by rebase * Desktop Wallet (py): update little stuff * Update some capacity/storage details * contribute doc nav update * fix image link in create diagram page * IAv3: Fix 'Ledgers' blurb * Update full history requirements with details from community members * add reviewer suggestions * Edits per @trippled review * Apply suggestions from peer review Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com> * FH: reword file size limit note per review * Update software ecosystem * updates per review * Minor tweaks to graphics * fixTypos * Update content/concepts/introduction/software-ecosystem.md Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * Update content/concepts/introduction/software-ecosystem.md Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * [JA] update AccountDelete cost * custom transactors doc * add doc to dactyl config * [JA] fix NonFungibleTokensV1_1 amendment status * [JA] update NFTokenOffer page * Remove old, unused XRP article (#2039) * add reviewer suggestions * Add tooling to check for file/nav consistency - From the repo top, run tool/check_file_consistency.py to look for Markdown files that exist in the "content/" directory but aren't used in the documentation. - New "enforce_filenames" filter prints a warning to console when building, if a file's path and filename don't match expectations based on its place in the nav and top heading. * File consistency checker: correctly handle filenames starting in _ * Remove unused old 'get started' and associated code * Create Resources section & reorg some files - Rename some files/folders based on their place in the nav - Move a bunch of non-documentation stuff, and docs on contributing code and/or docs to the new "Resources" section. - Known issue: nav spills into a second row on page widths between 993px-1110px. To be fixed in a later CSS update, maybe along with making the Resources dropdown multi-column. * Fix #2078 code tab bug CSS not built yet, to reduce merge conflicts. Won't have any effect until that happens. * fix Transaction JSON * [JA] translate contributing contents * fix contributing-to-documentation parent * fix contribute-code blurb * Top nav: add cols for Resources, fix broken links * CSS: fix top nav overflows * Fix broken link from redirect not in JA target * Top nav: add Infra to article types * Update contrib info & rename intro file * [ja] Update link to suggested first page to translate * [ja] fix contribute docs organization * Run private network with docker tutorial (#2065) * [NO-ISSUE] Run private network with docker tutorial Adds a tutorial page in the Infrastructure section on how to run a private XRPL network with Docker. Please let me know if you think this is a useful page to include for developers, whether the steps are clear or not, and if you have suggestions on what can be added to it. * Add minor link fixes and Japanese target * Apply suggestions from code review Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * Add link to ripple-docker-testnet setup scripts in See Also section * Update repo URL --------- Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * add intro gfx (#2036) * add intro gfx * Move graphic up * Update some graphics with their revised versions * Add updated version of the custodial vs non-custodial graphic --------- Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com> * Update to reflect current UNL publishers * [ja] update contributing Co-authored-by: tequ <git@tequ.dev> * Incorporate feedback on "What is XRP" page. (#2099) * Add trademark info for XRP * Revert section to previous state * Fix broken link (#2101) --------- Co-authored-by: Oliver Eggert <oeggert@ripple.com> Co-authored-by: ddawson <dennis.s.dawson@gmail.com> Co-authored-by: Maria Shodunke <mshodunke@ripple.com> Co-authored-by: tequ <git@tequ.dev> Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> Co-authored-by: develoQ <develoQ.jp@gmail.com> Co-authored-by: Maria Shodunke <maria-robobug@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com>
This commit is contained in:
Rome Reginelli
@@ -0,0 +1,168 @@
|
||||
---
|
||||
html: contribute-documentation.html
|
||||
parent: resources.html
|
||||
blurb: XRP Ledgerドキュメントのコントリビューションガイドです。
|
||||
---
|
||||
# ドキュメントへの貢献
|
||||
|
||||
XRP Ledger開発者ポータルへの貢献を検討いただきありがとうございます！
|
||||
|
||||
|
||||
私たちは、あなたが興味を持ってくださっていることにとても感動しています。XRP Ledger(XRPL)へ貢献することは、XRPLついて学ぶ素晴らしい機会です。
|
||||
|
||||
私たちはあなたのプルリクエストを喜んでレビューします。プロセスをできるだけ円滑に進めるため、このドキュメントを読み、記載されているガイドラインに従ってください。
|
||||
|
||||
## 当サイトについて
|
||||
|
||||
XRPL Dev Portalでは、開発者が開発を開始するためのサンプルコードやその他の情報を含む、XRP Ledgerの包括的なドキュメントを提供しています。
|
||||
|
||||
本プロジェクトの公式リポジトリは<https://github.com/XRPLF/xrpl-dev-portal>となっています。投稿の著作権はそれぞれの投稿者に帰属しますが、MIT[ライセンス](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE)の下で提供されなければなりません。
|
||||
|
||||
|
||||
|
||||
## リポジトリの構成
|
||||
|
||||
- [assets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/assets) - サイトのテンプレートで使用される静的ファイル。
|
||||
- [content/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content) - ドキュメントを構築するために使用されるソースファイル。ほとんどがMarkdownです。
|
||||
- [content/\_code-samples/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples) - ドキュメントで使用または参照されているコードサンプル。可能な限り、これらは完全に機能する/実行可能なスクリプトです。
|
||||
- [content/\_img-sources/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_img-sources) - ドキュメントで使用されている画像の元ファイル。`.uxf`ファイルは[Umlet](https://www.umlet.com/)で作成されたダイアグラムです。
|
||||
- [content/\_snippets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_snippets) - Dactylプリプロセッサを使用して、他のコンテンツファイルに挿入される再利用可能なMarkdownテキストの断片。
|
||||
- [img/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) - ドキュメントコンテンツで使用される画像。
|
||||
- [template/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/template) - HTMLを構築するためのテンプレートファイル。
|
||||
- [tool/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/tool) - フィルター、スタイルチェッカー・ルール等のスクリプト。
|
||||
- [styles/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/styles) - assetsフォルダにCSSファイルを生成するための元ファイル(SCSS)。
|
||||
- [`dactyl-config.yml`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/dactyl-config.yml) - サイトのメタデータを含むメイン設定ファイル。設定ファイルのフォーマットについては、[設定フォーマット](#設定ファイルのフォーマット)を参照してください。
|
||||
|
||||
## プルリクエストが承認されるための条件
|
||||
|
||||
レビューやマージが承認される前に、それぞれのプルリクエストは以下の条件を満たしていなければなりません。
|
||||
- インテグレーションテストに合格すること。
|
||||
- レビューの準備が整うまで、[Draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)としてください。
|
||||
- このリポジトリの[コード規約](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE_OF_CONDUCT.ja.md)を遵守してください。
|
||||
|
||||
## Dactylのセットアップ
|
||||
|
||||
ポータルは[Dactyl](https://github.com/ripple/dactyl)を使用して構築されています。
|
||||
|
||||
Dactylには[Python 3](https://python.org/)が必要です。[pip](https://pip.pypa.io/en/stable/)を使ってインストールしてください：
|
||||
|
||||
```
|
||||
pip3 install dactyl
|
||||
```
|
||||
|
||||
## サイトの構築
|
||||
|
||||
このリポジトリでは、[**Dactyl**](https://github.com/ripple/dactyl)を使用して、すべてのドキュメントのHTMLをビルドしています。[Dactylのセットアップ](#dactylのセットアップ)を行った後、プロジェクトのルートディレクトリからサイトをビルドすることができます。
|
||||
|
||||
```
|
||||
dactyl_build
|
||||
```
|
||||
|
||||
生成されたコンテンツは`out/`ディレクトリに出力されます。これらのコンテンツはウェブブラウザでファイルとして開いたり、ウェブサーバで静的コンテンツとして扱うことができます。
|
||||
|
||||
ルートディレクトリからリンクチェックやスタイルチェックを実行することもできます。
|
||||
|
||||
リンクチェックは出力フォルダを空にしてからビルドしてください。
|
||||
|
||||
```
|
||||
dactyl_link_checker
|
||||
```
|
||||
|
||||
スタイルチェックは実験的なものです。
|
||||
|
||||
```
|
||||
dactyl_style_checker
|
||||
```
|
||||
|
||||
## 設定ファイルのフォーマット
|
||||
|
||||
このリポジトリでは、`dactyl-config.yml`ファイルのメタデータとページの[frontmatter](https://dactyl.link/frontmatter.html)を使って、ヘッダー、フッター、サイドバー、パンくずリストなどのナビゲーション要素を生成します。
|
||||
|
||||
新しいページを追加する場合、`dactyl-config.yml`ファイルのpages配列の適切な位置に追加する必要があります。追加例は次のようになります。
|
||||
|
||||
```yaml
|
||||
- md: concepts/the-rippled-server/the-rippled-server.md
|
||||
targets:
|
||||
- en
|
||||
- ja # 翻訳コンテンツがない場合、全てのターゲットを対象とします。
|
||||
```
|
||||
|
||||
Markdownファイル自体は、以下のようなfrontmatterで始まる必要があります。
|
||||
|
||||
```yaml
|
||||
---
|
||||
html: the-rippled-server.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
|
||||
---
|
||||
```
|
||||
|
||||
少なくとも、ほとんどのページには `html`、`parent`、`blurb` フィールドが必要です(さらに、設定ファイルでは`md`フィールドと`targets`フィールドも必要です)。ここに、またはページの設定ファイルのエントリに任意のキーと値のペアを記述することができますが、以下のものが関係しています。
|
||||
|
||||
### 規約
|
||||
|
||||
ページを作成する際には、以下の規約に従ってください。
|
||||
|
||||
- HTMLのファイル名とMDのファイル名は、拡張子を除いて完全に一致していなければなりません。
|
||||
- ファイル名は"and"や"the"のような単語を含め、ページのタイトルと密接に一致する必要がありますが、スペースや句読点の代わりにハイフンを使用し、すべて小文字にする必要があります。例えば、`cash-a-check-for-an-exact-amount.md`のようにします。ページのタイトルを変更した場合は、ファイル名も変更する必要があります。(すでに別のURLで公開されている場合は、古いURLからのリダイレクトを残してください)
|
||||
- 常にh1ヘッダーでページを始めます。
|
||||
- ページの一番上のh1アンカーにはリンクせず、アンカーなしでページ自体にリンクしてください。これは翻訳時のリンク切れを防ぐのに役立ちます。以降のヘッダーへのリンクは問題ありません。
|
||||
- ページのタイトルに書式( _italics_ や`code font`など)を使わないでください。
|
||||
- Markdownファイルのテキストを折り返さないでください。
|
||||
- コードサンプルの場合、行は80文字以下になるようにしてください。
|
||||
- 迷ったら、[Ciro SantilliのMarkdownスタイルガイド (Writability Profile)](https://cirosantilli.com/markdown-style-guide/)に従ってください。
|
||||
- ランディングページはサブフォルダに入れ、フォルダと同じファイル名とします。例えば、"Accounts"ページグループのランディングページは`accounts/accounts.md`で、HTMLファイル名は`accounts.html`です。
|
||||
|
||||
**注意:** `index.md`は利用しないでください。
|
||||
|
||||
- Markdownやコードサンプルでは、インデントにタブ文字を使用しないでください。**JavaScript**のコードサンプルでは、1字下げにつき2個のスペースを使用してください。
|
||||
|
||||
### 技術用語
|
||||
|
||||
以下の単語やフレーズを説明通りに使用してください。
|
||||
|
||||
| 用語 | 避けるべき用語 | 備考 |
|
||||
|-------------------|----------------|-------|
|
||||
| API, APIs | API's, RPC | Application Programming Interface (アプリケーション・プログラミング・インターフェース)、ソフトウェアが他のソフトウェアと接続するための機能と定義のセット。 |
|
||||
| コアサーバ, XRP Ledgerのコアサーバ | `rippled` | `rippled`という名前は近い将来廃止される可能性が高いので、より一般的な名前で呼ぶことを推奨します。必要なときは、`rippled` をすべて小文字で、コードフォントで呼んでください。(発音は "リップルディー" で、"d" は UNIX の伝統に従って"daemon"を意味します)。
|
||||
| 金融機関 | 銀行, FI, PSP (決済サービスプロバイダ) | この用語は、_銀行_ や他の用語よりも幅広いビジネスを包含し、業界の専門用語の理解に依存しません。 |
|
||||
| レジャーエントリ | レジャーオブジェクト, ノード | XRP Ledgerの状態データ内の単一のオブジェクト。_レジャーオブジェクト_ という用語は、これらの一つを指すこともあれば、レジャー全体を指すこともあります。レジャーの状態データはグラフとして想定できるため、_ノード_ という用語が使われることもありましたが、_ノード_ には他の用途もあるため、混乱を招きます。 |
|
||||
| 流動性提供者 | マーケットメイカー | 2つの通貨または資産間の売買を提供し、多くの場合、取引間の価格差から利益を得る企業または個人。マーケットメーカーという用語は、法域によっては特定の法律上の定義があり、すべての同じ状況で適用されるとは限りません。 |
|
||||
| 悪質業者 | ハッカー | 個人、組織、または自動化されたツールなどによる、機密情報の取得、暗号化の解除、サービスの拒否、その他の安全なリソースへの攻撃を試みる可能性のあるもの。 |
|
||||
| PostgreSQL | Postgres | リレーショナルデータベース・ソフトウェアの特定のブランド。非公式な短いバージョンではなく、常に完全な名前を使用します。 |
|
||||
| オーダーブック | オファーブック | マッチングされ約定されるのを待っているトレード注文のコレクション。通常は取引レートごとにソートされています。 |
|
||||
| サーバ | ノード | サーバとは、ソフトウェアやハードウェアのことで、特にXRP Ledgerのピアツーピアネットワークに接続するものを指します。_ノード_ という用語はこの目的のために使われることもありますが、グラフのエントリやJavaScriptインタプリタであるNode.jsなど、他の意味でも多用されます。 |
|
||||
| ステーブルコイン発行者 | ゲートウェイ | 発行者とは、XRP Ledgerにおいてトークンを発行する組織です。ステーブルコインとは、発行者が外部の資産（例えば不換紙幣）に完全に裏付けられていることを約束しているトークンのことで、ステーブルコインの発行者は、その2つの資産を（場合によっては手数料を払って）交換する入出金操作を提供します。以前は、このユースケースを表現するために（特にリップル社によって）_ゲートウェイ_ という用語が使用されていましたが、業界の他の部分は代わりに _ステーブルコイン発行者_ を採用しました。 |
|
||||
| トランザクションコスト | トランザクション手数料 | XRP Ledgerでトランザクションを送信するために消費されるXRPの金額。これはトランザクションの`Fee`フィールドで指定されますが、_手数料_ という用語は誰かにお金を支払うことを意味するため、_コスト_ の方が望ましいです。 |
|
||||
| トークン | IOU, issuances, issues, 発行済み通貨 | XRP Ledgerのトークンは、_IOU_ という名前から想像されるように、レジャーの外部にある価値を表すことはできません。必要であれば、_代替可能トークン_ を使用して、非代替性トークン(NFT)と区別してください。 |
|
||||
| ウォレット | ウォレット | 文脈によっては、_ウォレット_ はハードウェア、ソフトウェア、暗号鍵ペア、またはオンラインサービスを指します。意味が明確になるように十分な文脈を提供するか、_キーペア_ や _クライアントアプリケーション_ などの別の表現を使用してください。 |
|
||||
| XRP | Ripple, リップル | XRPレジャーのネイティブデジタルアセットまたは暗号通貨。XRPはレジャーの外部の価値を表すトークンではありません。 |
|
||||
| XRP Ledger | Ripple, リップル, Ripple Network, リップルネットワーク, RCL | XRP Ledgerは、過去に様々な場面で「リップルネットワーク」や「リップルコンセンサスレジャー」あるいは「RCL」と呼ばれていました。これらの名称は、コアサーバーのリファレンス実装を開発しているRipple(Ripple Labs)の社名と類似しているため、紛らわしく、廃止されました。 |
|
||||
| XRPL | XRPL | _XRP Ledger_ の略です。_XRPL_ は不明瞭で、_XRP_ のタイプミスのように見えることがあります。 |
|
||||
|
||||
## Frontmatterのフィールド
|
||||
|
||||
このリポジトリのMarkdownファイルのfronmatterは任意のキーと値のペアを含むことができます。以下のフィールドは特定の用途や意味を持ちます。
|
||||
|
||||
| フィールド | 型 | 内容 |
|
||||
|:---------------------|:-----------------|:-----------------------------------|
|
||||
| `html` | String | ページの出力ファイル名。`.html`で終わり、ターゲット内で一意でなければなりません。翻訳版のページでは、ファイル名は英語版のページと同じにしてください。 |
|
||||
| `parent` | String | ページの「親」ページの`html`の値。このページがナビゲーションのどこに表示されるかを示します。 |
|
||||
| `blurb` | String | ページの要約文(プレーンテキストのみ)。ランディングページやソーシャルメディア上でリンクを展開する際のメタデータなど、さまざまな場所に表示されます。 |
|
||||
| `name` | String | ページ名(プレーンテキストのみ)。 Markdownコンテンツのあるファイルでは、Dactylがコンテンツの最初の行のヘッダーから自動的に検出できるため、これを省略する必要があります。これは通常、Markdownファイルを持たないランディングページやその他の特別なページでのみ提供されます。 |
|
||||
| `template` | String | このページで使用するテンプレートファイルのファイル名(`template/`ディレクトリ内)。ほとんどのページはデフォルトのテンプレートを使用します。`pagetype-category.html.jinja`テンプレートは最後に子ページのリストを表示します。特別な、あるいは特にユニークなレイアウトを持つページには、個別のテンプレートが必要になることがあります(通常、`page-`で始まります)。 |
|
||||
| `status` | String | XRP Ledgerメインネットでまだ有効になっていない修正に関連するページでは、`not_enabled`を使用します。これにより、ナビゲーションのページの横にツールチップ付きの"フラスコ"バッジが表示されます。 |
|
||||
| `nav_omit` | Boolean | ナビゲーション要素にこのページを表示しないようにするには`true`を使用します。 |
|
||||
| `top_nav_omit` | Boolean | ページトップのドロップダウンナビゲーションに表示しないようにするには、`true`を使用します。 |
|
||||
| `top_nav_level` | Number | トップナビのドロップダウンでページのインデントレベルを調整します。レベル`2`は、ドロップダウン内でその上のページの子のように表示されるようにインデントされます。 |
|
||||
| `sidebar` | String | U左右のサイドバーを非表示にするには、`disabled`を使用します(ページがベーステンプレートから派生したテンプレートを使用している場合)。 |
|
||||
| `fb_card` | String | Facebookでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 |
|
||||
| `twitter_card` | String | Twitterでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 |
|
||||
| `redirect_url` | String | `template: pagetype-redirect.html.jinja`でのみ使用します。ユーザがこのページに移動したときに、指定されたURLに自動的にリダイレクトします。 |
|
||||
| `cta_text` | String | このページにリンクする「call to action」ボタンに表示されるテキスト(特別なランディングページにて表示されます)。 |
|
||||
| `curated_anchors` | Array of Objects | 子ページと同様に、ランディングページに表示するためのアンカーです。配列の各オブジェクトは、人間が読める`name`フィールド(`"Available Modes"`など) と、リンク先のHTML IDを持つ`anchor`フィールド(`"#available-modes"`など)を持つ必要があります。 |
|
||||
| `skip_spell_checker` | Boolean | `true`を使用すると、Dactylのスタイルチェッカーがこのページのスペルチェックをスキップします。 |
|
||||
| `filters` | Array of Strings | このページで使用する追加フィルタのリストです。[フィルタ](https://github.com/ripple/dactyl/blob/master/README.md#filters)はPythonスクリプトで、ページ内容の事前または事後の追加処理を行います。 |
|
||||
| `canonical_url` | String | クエリパラメータを受け取るページの正規URLを提供します。検索エンジンやその他のツールは、ページにリンクする際にこれを使用する可能性があります。 |
|
||||
| `embed_xrpl_js` | Boolean | 最新版の[xrpl.js](https://js.xrpl.org)をこのページで読み込むには`true`を使用してください。 |
|
||||
@@ -0,0 +1,171 @@
|
||||
---
|
||||
html: contribute-documentation.html
|
||||
parent: resources.html
|
||||
blurb: Contribution guides for XRP Ledger documentation.
|
||||
---
|
||||
# Contribute Documentation
|
||||
|
||||
Thanks for considering a contribution to the XRP Ledger Developer Portal!
|
||||
|
||||
We're thrilled you're interested and your help is greatly appreciated. Contributing is a great way to learn about the XRP Ledger (XRPL).
|
||||
|
||||
We are happy to review your pull requests. To make the process as smooth as possible, please read this document and follow the stated guidelines.
|
||||
|
||||
|
||||
## About This Site
|
||||
|
||||
The XRPL Dev Portal provides comprehensive documentation of the the XRP Ledger, including sample code and other information for developers to start building.
|
||||
|
||||
The official source repository for the site is at <https://github.com/XRPLF/xrpl-dev-portal>. Contributions are copyright their respective contributors, but must be provided under the MIT [LICENSE](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
|
||||
|
||||
|
||||
|
||||
## Repository Layout
|
||||
|
||||
- [assets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/assets) - Static files used by the site's templates.
|
||||
- [content/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content) - Source files used to build the documentation. Mostly in Markdown.
|
||||
- [content/\_code-samples/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples) - Code samples used or referenced by the documentation. Where possible, these are fully functional / executable scripts.
|
||||
- [content/\_img-sources/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_img-sources) - Source files for images used in the documentation. Any `.uxf` files are diagrams made with [Umlet](https://www.umlet.com/).
|
||||
- [content/\_snippets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_snippets) - Reusable chunks of Markdown text that are included in other content files, using the Dactyl preprocessor.
|
||||
- [img/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) - Images used by the documentation contents.
|
||||
- [template/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/template) - Template files for building the HTML outputs.
|
||||
- [tool/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/tool) - Filters, style-checker rules, and other scripts.
|
||||
- [styles/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/styles) - Source files (SCSS) to generate the CSS files in the assets folder.
|
||||
- [`dactyl-config.yml`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/dactyl-config.yml) - Main config file, which contains the metadata for the site. For information on our conventions, see [Config Formatting](#config-formatting).
|
||||
|
||||
## Requirements for a Successful Pull Request
|
||||
|
||||
Before being considered for review or merging, each pull request must:
|
||||
- Pass continuous integration tests.
|
||||
- Be [marked as drafts](https://github.blog/2019-02-14-introducing-draft-pull-requests/) until they are ready for review.
|
||||
- Adhere to the [code of conduct](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE_OF_CONDUCT.md) for this repository.
|
||||
|
||||
## Dactyl Setup
|
||||
|
||||
The portal is built using [Dactyl](https://github.com/ripple/dactyl).
|
||||
|
||||
Dactyl requires [Python 3](https://python.org/). Install it with [pip](https://pip.pypa.io/en/stable/):
|
||||
|
||||
```
|
||||
pip3 install dactyl
|
||||
```
|
||||
|
||||
## Building the Site
|
||||
|
||||
This repo uses [**Dactyl**](https://github.com/ripple/dactyl) to build HTML display versions of all the documentation. After you've done the [Dactyl Setup](#dactyl-setup), you can build the site from the project root directory:
|
||||
|
||||
```
|
||||
dactyl_build
|
||||
```
|
||||
|
||||
This outputs the generated contents to the `out/` directory. These contents can be opened in a web browser as files or served as static content by a web server.
|
||||
|
||||
You can also run link checking or style checking from the root directory.
|
||||
|
||||
Link checking should be run after emptying the output folder and then building:
|
||||
|
||||
```
|
||||
dactyl_link_checker
|
||||
```
|
||||
|
||||
Style checking is experimental:
|
||||
|
||||
```
|
||||
dactyl_style_checker
|
||||
```
|
||||
|
||||
## Config Formatting
|
||||
|
||||
The templates in this repository use metadata from the `dactyl-config.yml` file as well as the pages' [frontmatter](https://dactyl.link/frontmatter.html) to generate navigation elements in the site, including header, footer, sidebars, and breadcrumbs.
|
||||
|
||||
If you add a new page, you must add it to the appropriate page in the pages array of the `dactyl-config.yml` file. An example entry looks like this:
|
||||
|
||||
```yaml
|
||||
- md: concepts/the-rippled-server/the-rippled-server.md
|
||||
targets:
|
||||
- en
|
||||
- ja # Include in all targets unless you have a translation
|
||||
```
|
||||
|
||||
The Markdown file itself should start with a frontmatter stanza such as the following:
|
||||
|
||||
```yaml
|
||||
---
|
||||
html: the-rippled-server.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
|
||||
---
|
||||
```
|
||||
|
||||
Most pages should have `html`, `parent` and `blurb` fields in the frontmatter, and the `md` and `targets` fields in the config file. For a fill list
|
||||
|
||||
### Conventions
|
||||
|
||||
Use the following conventions when creating a page:
|
||||
|
||||
- The HTML filename and MD filename should match exactly except for the file extension.
|
||||
- The filenames should closely match the title of the page, including words like "and" and "the", but should be in all lowercase with hyphens instead of spaces and punctuation. For example, `cash-a-check-for-an-exact-amount.md`. If you change the title of a page, change the filename too. (If it has already been published at another URL, leave a redirect from the old URL.)
|
||||
- Always start a page with a h1 header.
|
||||
- Don't link to the top h1 anchor of a page, link to the page itself without an anchor. This helps prevent broken links in translation. It's OK to link to later headers.
|
||||
- Don't use any formatting (like _italics_ or `code font`) in the title of the page.
|
||||
- Don't hard-wrap text in Markdown files.
|
||||
- For code samples, try to keep lines no longer than 80 columns wide.
|
||||
- When in doubt, follow [Ciro Santilli's Markdown Style Guide (Writability Profile)](https://cirosantilli.com/markdown-style-guide/).
|
||||
- Landing pages should be in subfolders and should have the same filename as the folder. For example, the landing page of the "Accounts" page group should be `accounts/accounts.md` with the HTML filename `accounts.html`.
|
||||
|
||||
**Warning:** Don't use `index.md`.
|
||||
|
||||
- Don't use tab characters for indentation in Markdown or code samples. Use 4 spaces per indent, except in **JavaScript** code samples, which should use 2 spaces per indent.
|
||||
|
||||
### Terminology
|
||||
|
||||
Use the following words and phrases as described:
|
||||
|
||||
| Term | Terms to Avoid | Notes |
|
||||
|-------------------|----------------|-------|
|
||||
| API, APIs | API's, RPC | Application Programming Interface, a set of functions and definitions for software to connect to other software. |
|
||||
| core server, core XRP Ledger server | `rippled` | The `rippled` name is probably going to be retired in the near future, so it's better to refer to it by the more generic name. When necessary, refer to `rippled` in all lowercase and code font. (It's pronounced "ripple dee", and the "d" stands for "daemon" per UNIX tradition.)
|
||||
| financial institution | bank, FI, PSP (payment services provider) | This term encompasses a wider range of businesses than just _bank_ or other terms and does not rely on an understanding of industry jargon. |
|
||||
| ledger entry | ledger object, node | A single object inside the state data of the XRP Ledger. The term _ledger object_ could refer to one of these or to the whole ledger. The term _node_ was sometimes used for this case because the ledger's state data can be envisioned as a graph, but this is confusing because _node_ has other uses. |
|
||||
| liquidity provider | market maker | A business or individual who offers to exchange between two currencies or assets, often deriving income from the price differential between trades. The term _market maker_ has a specific legal definition in some jurisdictions and may not apply in all the same circumstances. |
|
||||
| malicious actor | hacker | A person, organization, or even an automated tool which might attempt to acquire secrets, break encryption, deny service, or otherwise attack a secure resource. |
|
||||
| a NFT | an NFT | A NFT object in the XRP Ledger tracks or represents a non-fungible token. Pronounced "nifty" and written _a NFT_ rather than _an NFT_. |
|
||||
| PostgreSQL | Postgres | A specific brand of relational database software. Always use the full name, not an informal short version. |
|
||||
| order book | orderbook, offer book | A collection of trade orders waiting to be matched and executed, typically sorted by exchange rate. Use two words. |
|
||||
| server | node | A server is software and/or hardware, especially the ones that connect to the XRP Ledger peer-to-peer network. The term _node_ is sometimes used for this purpose but is also overloaded with other meanings including entries in a graph and Node.js, a JavaScript interpreter. |
|
||||
| stablecoin issuer | gateway | An issuer is the organization that issues a token in the XRP Ledger. A stablecoin is a token where the issuer promises that it is fully backed by some outside asset (such as fiat currency), with the stablecoin issuer providing deposit and withdraw operations to convert between the two (possibly for a fee). Previously the term _gateway_ was used (especially by Ripple, the company) to describe this use case, but the rest of the industry adopted _stablecoin issuer_ instead. |
|
||||
| transaction cost | transaction fee | The amount of XRP burnt to send a transaction in the XRP Ledger. Even though this is specified in the `Fee` field of transactions, the term _fee_ implies that the money is paid to someone, so _cost_ is preferable. |_
|
||||
| trust line | trustline | Use two words. A trust line is a relationship between two accounts in the XRP Ledger that tracks a balance of tokens between those accounts. |
|
||||
| tokens | IOUs, issuances, issues, issued currencies | A token in the XRP ledger may not represent money owed outside of the ledger as the name _IOU_ implies. Specify _fungible tokens_ if necessary to distinguish from non-fungible tokens. |
|
||||
| wallet | wallet | Depending on the context, _wallet_ could refer to hardware, software, a cryptographic key pair, or an online service. Be sure to provide enough context that the meaning is clear, or use an alternative such as _key pair_ or _client application_. |
|
||||
| WebSocket | web socket, Websockets | A two way protocol for communication on the web. Always singular and in CamelCase. |
|
||||
| XRP | XRPs, ripples | The native digital asset, or cryptocurrency, of the XRP Ledger. XRP is not a token. |
|
||||
| the XRP Ledger | XRP Ledger (no the), Ripple, Ripple Network, RCL | The XRP Ledger was called _the Ripple network_ and the _Ripple Consensus Ledger_ or _RCL_ at various times in the past. These names were confusing and have been retired because of their similarity to the name of the company, Ripple (formerly Ripple Labs) which develops the reference implementation of the core server. |
|
||||
| XRPL | XRPL | Short for _XRP Ledger_. As much as possible, spell out _XRP Ledger_ instead; _XRPL_ is cryptic and looks like it could be a typo for _XRP_. |
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
The fronmatter for a Markdown file in this repo can contain arbitrary key-value pairs; the config file entry for the page can add to those or override them. The following fields have specific uses or meaning:
|
||||
|
||||
| Field | Type | Contents |
|
||||
|:---------------------|:-----------------|:-----------------------------------|
|
||||
| `html` | String | Output filename for the page. Should end in `.html` and MUST be unique within the target. For translated pages, leave the filename the same as the English version page. |
|
||||
| `parent` | String | The exact, unique `html` value of this page's "parent" page. Indicates where this page should appear in the navigation. |
|
||||
| `blurb` | String | Human-readable summary of the page. (Plain text only.) Should be about 1 sentence long. This appears in various places, including landing pages and metadata used in unfurling links on social media. |
|
||||
| `name` | String | Human-readable page name. (Plain text only.) For files with Markdown content, you should omit this so that Dactyl can automatically detect it from a header on the first line of the contents instead. This is usually only provided on landing pages or other special pages with no Markdown source file. |
|
||||
| `template` | String | The filename of a template file to use (in the `template/` directory) for this page. Most pages should use the default template. The `pagetype-category.html.jinja` template shows a list of child pages at the end. Pages with special or particularly unique layouts may need individual templates (conventionally, starting with `page-`). |
|
||||
| `status` | String | Use the value `not_enabled` on pages relating to an amendment that is not yet enabled on the XRP Ledger mainnet. This displays a "flask" badge with a tooltip next to the page in the navigation. |
|
||||
| `nav_omit` | Boolean | Use `true` to cause this page not to appear in any navigation elements. |
|
||||
| `top_nav_omit` | Boolean | Use `true` to cause this page not to appear in the page top dropdown navigation. |
|
||||
| `top_nav_level` | Number | Adjust the indentation level for the page in the top nav dropdowns. Level `2` is indented to appear like a child of the page above it in the dropdown. |
|
||||
| `sidebar` | String | Use `disabled` to hide the left and right sidebars (if the page uses a template derived from the base template) |
|
||||
| `fb_card` | String | Filename of an image (in `assets/img/`) to use when unfurling links to this page on Facebook. |
|
||||
| `twitter_card` | String | Filename of an image (in `assets/img/`) to use when unfurling links to this page on Twitter. |
|
||||
| `redirect_url` | String | Use with `template: pagetype-redirect.html.jinja` only. Automatically redirect the user to the provided URL when they navigate to this page. |
|
||||
| `cta_text` | String | Text to appear in "call to action" buttons that link to this page (on special landings). |
|
||||
| `curated_anchors` | Array of Objects | A set of anchors in this page to show, similar to child pages, in landings. Each object in the array should have a human-readable `name` field (such as `"Available Modes"`) and an `anchor` field with the HTML ID to link to (such as `"#available-modes"`). |
|
||||
| `skip_spell_checker` | Boolean | Use `true` to make the Dactyl's style checker skip spell-checking this page. |
|
||||
| `filters` | Array of Strings | A list of additional filters to use on this page. [Filters](https://github.com/ripple/dactyl/blob/master/README.md#filters) are Python scripts that provide additional pre- or post-processing of page contents. |
|
||||
| `canonical_url` | String | Provides the canonical URL for a page that takes query parameters. Search engines and other tools may use this when linking to the page. |
|
||||
| `embed_xrpl_js` | Boolean | Use `true` to have the latest version of [xrpl.js](https://js.xrpl.org) loaded on the page. |
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
html: creating-diagrams.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: ライトモードとダークモードの設定で適切に動作する図を作成します。
|
||||
---
|
||||
# 図の作成
|
||||
|
||||
このサイトには、SVGの図をライト・ダークモード用に自動的に再カラーリングするコードが含まれています。これは単に画像を反転させるだけではありません。再カラーリングは（ボトムライトに見えないように）グラデーションを同じ方向に保ち、色をその逆ではなくテーマに合った同等なものに置き換えます。例えば、"Ripple blue"は、その逆のオレンジではなく、XRPLグリーンに再カラーリングされます。
|
||||
|
||||
|
||||
|
||||
テーマを意識した再カラーリングでは、図のSVG形式の単一のソースファイルを使用し、CSSを使用して現在のテーマ（明暗）に合わせて再カラーリングされた図を生成します。ユーザがテーマを変更すると、図は即座にそれに合わせて変更されます。
|
||||
|
||||
テーマに対応した図をドキュメントに含めるには、以下のような構文で`include_svg`フィルタを使用します。
|
||||
|
||||
```jinja
|
||||
{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "図1：XRP Ledgerの要素") }}
|
||||
```
|
||||
|
||||
この構文の前後は空行にしてください。該当のSVGファイルは、リポジトリのトップレベルにある[`img/`](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img)フォルダか、そのサブフォルダにあるはずです。2番目の引数は _表題_ で、ユーザが図の上にマウスを置いたときに表示されます。
|
||||
|
||||
作成されたSVGファイルはMarkdownファイルに直接挿入されます。1点制限事項として、箇条書きリストやテーブルのような他のMarkdown構造の中では使用することはできません。
|
||||
|
||||
> **注記:** フィルタのソースコードは[`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py)です。これは`lxml`がサイトを構築するための依存関係の一つである理由でもあります。
|
||||
|
||||
## Making Diagrams
|
||||
|
||||
図を作成する際には、再カラーリングが正しく適用されるように注意する必要があります。そうしないと、もう一方のテーマ用に再カラーリングしたときに、一部の要素が見えなくなる可能性があります(例えば、白地に白や黒地に黒など)。テーマを考慮したダイアグラムのコードは、[Umlet](https://www.umlet.com/)または[Google Draw](https://docs.google.com/drawings/)のいずれかを使用して作成され、SVGとしてエクスポートされた図をサポートしています。また、図を作成する際には、以下のガイドラインに従ってください。
|
||||
|
||||
- デフォルトでライトモード用の図を作成します。透明な背景色を使用してください。
|
||||
- テーマ対応ダイアグラムのコードがマッピングしている色のみを使用します。色の完全なリストを含む、このためのコードは[`styles/_diagrams.scss`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/_diagrams.scss)にあります。必要であれば、SCSSコードを拡張することで、新しい色を追加することができます。(作業が終わったら、CSSを再エクスポートすることを忘れないでください。[style README](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/README.md)を参照してください)。
|
||||
- 可能な限り、埋め込みアイコン/画像の代わりにベクター図形を使用してください。画像の上にテキストを配置する必要がある場合は、テキスト要素に無地の背景を追加し、テーマがマッピングしている色のいずれかを使用してください。
|
||||
- テキストを含む透明な要素を、異なる背景色を持つ要素の上に重ねないでください。テキストを含む要素に直接背景色を適用してください。
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
html: creating-diagrams.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Create diagrams that interact properly with light and dark mode settings.
|
||||
---
|
||||
# Creating Diagrams
|
||||
|
||||
The site contains code to automatically recolor SVG diagrams for light and dark mode. This is more than just inverting images. The recoloring keeps gradients going the same direction (so that things don't look bottom-lit) and replaces colors with equivalents that fit with the theme rather than their inverse. For example, "Ripple blue" gets recolored to XRPL green, not its inverse orange. Example:
|
||||
|
||||
|
||||
|
||||
Theme-aware recoloring uses a single source file in SVG format for diagrams, and produces diagrams that are recolored to match the current theme (light/dark) using CSS. If the user changes their theme, the diagrams immediately change to match it.
|
||||
|
||||
To include a theme-aware diagram in a document, use the `include_svg` filter with syntax such as the following:
|
||||
|
||||
```jinja
|
||||
{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "Figure 1: XRP Ledger Elements") }}
|
||||
```
|
||||
|
||||
Leave empty lines before and after this syntax. The SVG file in question should be in the [`img/`](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) folder at the top level of the repo, or a subfolder of it. The second argument is _title text_, which appears when the user hovers their mouse over the diagram, and can also be used by other software (such as screen readers) to caption the diagram.
|
||||
|
||||
The resulting SVG file is inlined directly into the Markdown file. One limitation is that you can't use it inside other Markdown structures such as bulleted lists or tables.
|
||||
|
||||
> **Note:** The filter source code is [`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py). This is also the reason that `lxml` is one of the dependencies for building the site.
|
||||
|
||||
## Making Diagrams
|
||||
|
||||
You have to take care when creating diagrams so that the recoloring applies correctly; otherwise, some elements might be invisible (white-on-white or black-on-black, for example) when recolored for the other theme. The theme-aware diagrams code supports diagrams created using either [Umlet](https://www.umlet.com/) or [Google Draw](https://docs.google.com/drawings/) and exported as SVG. Additionally, you should follow these guidelines when making diagrams:
|
||||
|
||||
- Create diagrams for light mode by default. Use a transparent background color.
|
||||
- Only use colors that the theme-aware diagrams code has mappings for. The code for this, including the full list of colors, is in [`styles/_diagrams.scss`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/_diagrams.scss). If needed, you can add new colors by extending the SCSS code. (Don't forget to re-export the CSS when you're done. See the [styles README](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/README.md).)
|
||||
- Use actual vector shapes instead of embedded icons/images whenever possible. If you need to put text on top of an image, add a solid background to the text element and use one of the colors the theme has mappings for.
|
||||
- Don't layer transparent elements containing text on top of elements with different background colors. Apply a background color directly to the element that contains the text.
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
html: documentation-translations.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: このウェブサイトにある文書の翻訳に貢献し、維持する方法を学びましょう。
|
||||
---
|
||||
# 翻訳
|
||||
|
||||
XRP Ledger Dev Portalは大部分が英語で書かれているため、一般的には英語版が最新かつ正確なバージョンです。しかしながら、XRP Ledgerのソフトウェアとコミュニティへのリーチを広げるために、このリポジトリには翻訳版のドキュメントも含まれています。私たちは、他の言語を理解するコミュニティのメンバーが、開発ポータルの内容を母国語で翻訳することを大いに歓迎します。
|
||||
|
||||
`dactyl-config.yml`には利用可能な言語ごとに"target"項目があります(現在、利用可能な言語は英語と日本語です)。このエントリには、次のようにテンプレートファイルで使用される文字列の定義が含まれます。
|
||||
|
||||
```yaml
|
||||
- name: en
|
||||
lang: en
|
||||
display_name: XRP Ledger Dev Portal
|
||||
# These github_ fields are used by the template's "Edit on GitHub" link.
|
||||
# Override them with --vars to change which fork/branch to edit.
|
||||
github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
|
||||
github_branch: master
|
||||
strings:
|
||||
blog: "Blog"
|
||||
search: "Search site with Google..."
|
||||
bc_home: "Home"
|
||||
# ...
|
||||
```
|
||||
|
||||
また、トップレベルの`languages`リストもあり、サポートされている各言語が定義されています。各言語のショートコードは[IETF BCP47](https://tools.ietf.org/html/bcp47)に従ったショートコードでなければなりません。例えば、"en"は英語、"es"はスペイン語、"ja"は日本語、"zh-CN"は簡体字中国語、"zh-TW" は繁体字中国語 (台湾で使用) などです。`display_name`フィールドはその言語でネイティブに書かれた言語名を定義します。`prefix`フィールドはその言語のサイトへのハイパーリンクで使用する接頭辞を定義します。次に`languages`の定義例を示します。
|
||||
|
||||
```yaml
|
||||
languages:
|
||||
- code: en
|
||||
display_name: English
|
||||
prefix: "/"
|
||||
- code: ja
|
||||
display_name: 日本語
|
||||
prefix: "/ja/"
|
||||
```
|
||||
|
||||
同じ`dactyl-config.yml`ファイルには、XRP Ledger Dev Portalの各コンテンツページのエントリがあります。ページが翻訳されている場合、各翻訳ごとに個別の項目があり、その翻訳の“ターゲット"にリンクされています。ページがまだ翻訳されていない場合、すべてのターゲットで英語版が使用されます。(新しいページが英語のみ追加され、他の言語が提供されない場合、リンクチェッカーはそれをリンク切れとして報告します。)
|
||||
|
||||
ページを翻訳するということは、そのページのエントリを他の言語と分割するということです。ページのメタデータは`dactyl-config.yml`ファイルか、ページのMarkdownファイルの先頭にあるfrontmatterに設定します。
|
||||
|
||||
| フィールド | 備考 |
|
||||
|----------|------|
|
||||
| `html` | ページのHTMLファイル名。慣例により、これはすべての言語バージョンで同じであるべきです。 |
|
||||
| `md` | ページのMarkdownソースファイル。翻訳されたMarkdownソースファイルは英語版と同じファイル名を使用してください。ただし、拡張子は英語版の`.md`ではなく、`.{言語コード}.md`を使用してください。例えば、日本語の翻訳ファイルの拡張子は `.ja.md` です。 |
|
||||
| `blurb` | ページの簡単な要約。これは翻訳されるべきです。このテキストは、検索エンジン最適化のためのメタデータや、自動生成されるランディングページで使用されます。 |
|
||||
|
||||
`server_info`メソッドページの英語と日本語の記入例：
|
||||
|
||||
```yaml
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
|
||||
targets:
|
||||
- ja
|
||||
```
|
||||
|
||||
翻訳されていないページの記入例：
|
||||
|
||||
```yaml
|
||||
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
```
|
||||
|
||||
## 始めるにあたって
|
||||
|
||||
XRP Ledger Dev Portalをあなたの母国語に翻訳したい場合は、まず["What is the XRP Ledger?" file]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/concepts/introduction/what-is-the-xrp-ledger.md)から始めてください。
|
||||
|
||||
このファイルを`xrp-ledger-overview.{言語コード}.md`として保存します。ここで`{言語コード}`は[IETF BCP47](https://tools.ietf.org/html/bcp47)の言語コードです。(例えば、スペイン語は"es"、日本語は"ja"、簡体字中国語は"zh-CN"、台湾で使われている繁体字中国語は"zh-TW"などです)。そして、あなたのファイルをこのリポジトリに追加する[プルリクエスト](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)を作成してください。リポジトリメンテナの誰かが、サイトに言語を追加するために必要なその他の設定を手伝ってくれるでしょう。
|
||||
|
||||
Markdownコンテンツファイルでは、以下の規則に従ってください。
|
||||
|
||||
- 改行文字(`\n`)のみ（Unixスタイル）。キャリッジリターン文字(`\r`)は使用しないでください（Windowsスタイル）。
|
||||
- UTF-8エンコーディングを使用してください。バイトオーダーマークの使用は避けてください。
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
html: documentation-translations.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Learn how to contribute and maintain translations of the documentation on this website.
|
||||
---
|
||||
# Translations
|
||||
|
||||
The XRP Ledger Dev Portal is mostly written in English, so the English version is generally the most up-to-date and accurate version. However, to broaden the reach of the XRP Ledger software and community, this repository also contains translated versions of the documentation. We strongly encourage members of the community who understand other languages to contribute translations of the dev portal contents in their native languages.
|
||||
|
||||
The `dactyl-config.yml` contains a "target" entry for each available language. (Currently, the available languages are English and Japanese.) This entry includes a dictionary of strings used in the template files. For example:
|
||||
|
||||
```yaml
|
||||
- name: en
|
||||
lang: en
|
||||
display_name: XRP Ledger Dev Portal
|
||||
# These github_ fields are used by the template's "Edit on GitHub" link.
|
||||
# Override them with --vars to change which fork/branch to edit.
|
||||
github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
|
||||
github_branch: master
|
||||
strings:
|
||||
blog: "Blog"
|
||||
search: "Search site with Google..."
|
||||
bc_home: "Home"
|
||||
# ...
|
||||
```
|
||||
|
||||
There is also a top-level `languages` listing that defines some properties for each supported language. The short code for each language should be short code according to [IETF BCP47](https://tools.ietf.org/html/bcp47). For example, "en" for English, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese (as used in Taiwan), and so on. The `display_name` field defines the language's name as written natively in that language. The `prefix` field defines a prefix to be used in hyperlinks to that language's version of the site. Example `languages` definition:
|
||||
|
||||
```yaml
|
||||
languages:
|
||||
- code: en
|
||||
display_name: English
|
||||
prefix: "/"
|
||||
- code: ja
|
||||
display_name: 日本語
|
||||
prefix: "/ja/"
|
||||
```
|
||||
|
||||
The same `dactyl-config.yml` file contains an entry for each content page in the XRP Ledger Dev Portal. If a page has been translated, there is a separate entry for each translation, linked to the "target" for that translation. If a page has not yet been translated, the English version is used across all targets. (If a new page is added only to English and not other languages, the link checker reports that as a broken link.)
|
||||
|
||||
Translating a page means separating out the entry for that page in the other language. Here are some tips for translating the page's metadata, which can be in either the `dactyl-config.yml` file or the frontmatter at the top of the page's Markdown file:
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| `html` | The HTML file name of the page. By convention, this should be the same across all language versions. |
|
||||
| `md` | The Markdown source file for the page. Translated Markdown source files should use the same filename as the English-language version except that the file extension should be `.{language code}.md` instead of only `.md` for English. For example, Japanese translated files end in `.ja.md`. |
|
||||
| `blurb` | A short summary of the page. This should be translated. This text is used in metadata for search engine optimization and also on automatically-generated landing pages. |
|
||||
|
||||
|
||||
Example of English and Japanese entries for the `server_info` method page:
|
||||
|
||||
```yaml
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
|
||||
targets:
|
||||
- ja
|
||||
```
|
||||
|
||||
Example entry for a page that isn't translated:
|
||||
|
||||
```yaml
|
||||
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
```
|
||||
|
||||
## Where to Start
|
||||
|
||||
If you want to translate the XRP Ledger Dev Portal into your native language of choice, start with the ["What is the XRP Ledger?" page]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/concepts/introduction/what-is-the-xrp-ledger.md), which introduces the core concepts behind the XRP Ledger.
|
||||
|
||||
Save the file as `what-is-the-xrp-ledger.{language code}.md`, where `{language code}` is the [IETF BCP47](https://tools.ietf.org/html/bcp47) language code. (For example, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese as used in Taiwan, and so on.) Then open a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) adding your file to this repository. One of the repository's maintainers can help with the other necessary setup to add the language to the site.
|
||||
|
||||
For the Markdown content files, please use the following conventions:
|
||||
|
||||
- Line-feed newline characters (`\n`) only (Unix style). Do not use carriage return (`\r`) characters (Windows style).
|
||||
- Use UTF-8 encoding. Avoid the use of Byte-order marks.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
html: tutorial-guidelines.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: このサイトのチュートリアルの構成と、質の高いチュートリアルを投稿するためのガイドラインを学びましょう。
|
||||
---
|
||||
# チュートリアルガイドライン
|
||||
|
||||
私たちは、開発者が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ファイルを使用してください。
|
||||
|
||||
可能な限り、他のモジュールのコードを再利用してください。以前のモジュールの動作を変更する必要がある場合があります。関数名をオーバーロードするか、モジュールを修正して別の名前で保存してください。
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
html: tutorial-guidelines.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Learn how this site's tutorials are structured and guidelines for contributing quality tutorials.
|
||||
---
|
||||
# Tutorial Guidelines
|
||||
|
||||
We are creating a modular tutorial framework that allows developers to learn how transactions and requests work on the XRP Ledger. Developers can review the modules to learn about business solutions, and potentially repurpose the scripts in their own applications.
|
||||
|
||||
|
||||
# Rationale
|
||||
|
||||
What a developer wants comes down to two things:
|
||||
|
||||
1. Sample code snippets they can copy and paste into their own applications.
|
||||
2. Complete API reference documentation.
|
||||
|
||||
Keep the conceptual information to a minimum – only the information necessary to complete the tutorial. For background or deeper understanding, provide links to the conceptual topics at the end of the tutorial, if needed.
|
||||
|
||||
Modular tutorials follow Malcolm Knowles’ six assumptions for designing adult learning:
|
||||
|
||||
1. Adults need to know why they need to learn something.
|
||||
2. Adults need to build on their experience.
|
||||
3. Adults have a need to feel responsible for their learning.
|
||||
4. Adults are ready to learn if training solves an immediate problem.
|
||||
5. Adults want their training to be problem focused.
|
||||
6. Adults learn best when motivation comes intrinsically.
|
||||
|
||||
Add into that Ralph Smedley’s quote, “We learn best in moments of enjoyment.” Taking a lighter touch helps to relax the learner so that the material flows into their brain with less resistance.
|
||||
|
||||
|
||||
# Sample Code vs. Tasks vs. Concepts vs. Tutorials
|
||||
|
||||
To date, there have been some blurred lines where different types of documentation show up as _Tutorials_. Here are some comparisons that help define the distinction.
|
||||
|
||||
|
||||
## Sample Code
|
||||
|
||||
Sample code is well commented snippets or applications that illustrate best practices for implementing a feature of the API. Sample code is modular and reusable with little customization required.
|
||||
|
||||
Sample code is desirable, because advanced users can typically scan the example and use it immediately without a formal tutorial. It can also be used by others as a basis for tutorials. Sample code developers can focus on what they do well, while technical writers and support personnel can use the samples to create quality training materials.
|
||||
|
||||
|
||||
## Tasks
|
||||
|
||||
Tasks are step-by-step instructions for how to accomplish a specific result. For example, “Installing rippled on a Red Hat Linux Server.” Task documentation is not intended to be particularly educational. It frequently describes tasks that are only performed one time per implementation, or maintenance tasks that always follow a familiar pattern. Tasks provide troubleshooting guidance, since there are likely variables that the user must adjust based on the specifics of their use case.
|
||||
|
||||
|
||||
## Concepts
|
||||
|
||||
Conceptual information describes elements of the API, how they work, and when to use them. If a tutorial requires lengthy explanations before or during the programming tasks, consider how you might separate the exposition into a new topic, or link to existing topics that set the proper context.
|
||||
|
||||
For example, three paragraphs of context and a single line of code would be a concept, not a tutorial.
|
||||
|
||||
|
||||
## Tutorials
|
||||
|
||||
Tutorials begin with sample code that illustrates best practices for implementing a feature. They take the developer step-by-step through the development process, explaining the purpose of each block of code.
|
||||
|
||||
Tutorials further combine a number of features to work together to solve a business problem. They describe the straightforward sunny day path to complete a task. Then, the tutorial might suggest modifications that let the developer try several different scenarios. Due to their focus on a certain limited scope of behavior, tutorials should not require extensive troubleshooting information.
|
||||
|
||||
|
||||
## Use Cases
|
||||
|
||||
Use cases describe how to pull together multiple features to create a practical application that solves a business problem. They provide context and assistance with the decision making process, then provide links to the appropriate topics for each step of implementation.
|
||||
|
||||
|
||||
# Tutorial Components
|
||||
|
||||
This section describes the elements of the modular tutorials used on XRPL.org.
|
||||
|
||||
|
||||
## Sample Application
|
||||
|
||||
XRPL tutorial code samples are modular in nature. For example, Script 1 demonstrates how to create a test account, access the XRP Ledger, and transfer XRP between accounts. Any further samples can reuse the functions in Script 1.
|
||||
|
||||
Create a new script with the specific, minimal function code required to demonstrate the practical solution to a business problem. The examples should be incremental, with just enough behaviors to illustrate a business process.
|
||||
|
||||
For example, the first NFT tutorial shows how to mint, retrieve, and burn an NFT. The next tutorial shows how to create and accept a sell offer, and create and accept a buy offer.
|
||||
|
||||
Don’t focus too much on the UX of the application, unless the look and feel is pertinent to the topic. Use the standard CSS file with the look and feel for all of the tutorials.
|
||||
|
||||
Reuse the code from other modules when possible. There might be situations where you need to modify the behavior from an earlier module. You can either overload the function name or modify the module and save it with a different name.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
html: tutorial-structure.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: 一般的なチュートリアルの構成要素の要約です。
|
||||
---
|
||||
# チュートリアルの構成
|
||||
|
||||
各XRP Ledgerチュートリアルは、同一のフォーマットで構成されています。
|
||||
|
||||
1. チュートリアルで説明する機能の簡単な説明。
|
||||
2. コードを実行するための前提条件(必要な場合)、またはサンプルコードへのリンク。
|
||||
3. チュートリアルの機能の使用例。
|
||||
4. サンプルコードの解説と、そのスクリプトの特徴的な要素の紹介。
|
||||
5. 次のステップとして試すべき概念的な情報や優れたチュートリアルへのリンク。
|
||||
|
||||
セットアップ(前提条件)と使用方法とコード開発は分けて考えましょう。これらはそれぞれ異なる活動であり、それぞれ脳の異なる領域を動かします。この3つの要素を一度に考えようとすると、混乱につながります。
|
||||
|
||||
## 説明
|
||||
|
||||
|
||||
|
||||
そのサンプルが何を示しているかを記載してください。可能であれば、各サンプルには関連する特定のタスクを達成するための手順を記述してください。(NFTの売却オファーの作成、売却オファーの受け入れ、売却オファーの削除など)。チュートリアルで説明されている内容を理解するのに十分なコンセプトに関する情報を記載し、必要であれば、追加情報へのリンクも記載します。
|
||||
|
||||
## 前提条件
|
||||
|
||||
|
||||
|
||||
必要なソフトウェアと、チュートリアルを実行するために必要なすべてのサンプルコードへのリンクを提供します。必要であれば、サードパーティのツールの使い方を簡単に説明しますが、ユーザが自由に深く掘り下げることができるように、ソースとなるウェブサイトへのリンクを提供します。
|
||||
|
||||
## 使用例
|
||||
|
||||
|
||||
|
||||
チュートリアルのアプリケーションの完成した動作例を提供することから始めましょう。これは、ソフトウェアを使って問題を解決するチャンスです。
|
||||
|
||||
チュートリアルの各ステップにはスクリーンショットを使用してください。これによって、ユーザは自分でコードを実行しなくてもチュートリアルを理解することができます。もちろん、コードを実行することが _望ましい_ ですが、これにりユーザに選択肢を与えることができます。
|
||||
|
||||
適切な条件におけるシナリオを記述してください。インターネットへの接続が途切れなければ、アプリケーションは問題なく動作するはずです。チュートリアルに関連しないトラブルシューティングの情報を提供しないでください。
|
||||
|
||||
## コード解説
|
||||
|
||||
|
||||
|
||||
コードを1ブロックずつ見ていきましょう。既に説明したトピックを繰り返さないでください。サンプルコードには、HTML構文のような基本的な部分のプログラミング方法については、その実装に独自なものがない限り、詳細な説明はしないでください。
|
||||
|
||||
強調すべき重要なことは、XRPLとのやりとりはすべてトランザクションかリクエストであり、すべてのトランザクションとリクエストは本質的に同じであるということです。私たちが提供するサンプルコードは、トランザクションやリクエストを準備する方法と、返された結果を処理する方法を示しています。1つのトランザクションやリクエストをどのように送信しどのようなレスポンスを返すかを知ることは、他のトランザクションやリクエストの処理について非常に良いヒントとなります。
|
||||
|
||||
(技術的には、リクエストに似た第3のカテゴリーがあります。[Subscriptionメソッド](subscription-methods.html)をご覧ください)。
|
||||
|
||||
## 関連項目
|
||||
|
||||
|
||||
|
||||
チュートリアルの最後には、追加の資料、概念的な情報、学習のにおいて有益な次のステップとなるチュートリアルへのリンクを提供します。
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
html: tutorial-structure.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: A summary of the parts of a standard tutorial.
|
||||
---
|
||||
# Tutorial Structure
|
||||
|
||||
Each XRP Ledger tutorial follows the same format.
|
||||
|
||||
1. A brief description of the features illustrated in the tutorial.
|
||||
2. Prerequisites for running the code, if needed, or links to the sample code.
|
||||
3. Usage examples of the features in the tutorial.
|
||||
4. A code walkthrough of the sample application, highlighting unique elements in the scripts.
|
||||
5. See Also, with links to conceptual information or good tutorials to try as a next step.
|
||||
|
||||
Separate setup (prerequisites) from usage from code development. These are each different activities that engage different areas of the brain. Trying to think of all three elements at once leads to confusion and headaches.
|
||||
|
||||
## Description
|
||||
|
||||
|
||||
|
||||
List what the sample demonstrates. If possible, each example should describe the steps to accomplish specific related tasks. (For example, create a NFT Sell Offer, Accept a Sell Offer, Delete a Sell Offer.) There should be enough conceptual information to understand what the tutorial illustrates, with links to additional conceptual information, if needed.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
|
||||
Provide links to any required software and to all of the example code needed to run the tutorial. If necessary, give simple instructions for using third-party tools, but provide a link to the source website for the customer to do a deeper dive at their leisure.
|
||||
|
||||
## Usage Example
|
||||
|
||||
|
||||
|
||||
Start by providing a finished, working example of the tutorial application. This is an opportunity for immediate success working with the software to solve a problem.
|
||||
|
||||
Use screenshots for each step of the tutorial – these allow the user to understand the tutorial without having to run the code themselves. Of course we _want_ them to run the code, but this gives them a choice.
|
||||
|
||||
Describe the sunny day scenario. The application should run without problems if there is an uninterrupted connection to the internet. Don’t provide a lot of troubleshooting information, unless it’s pertinent to the tutorial.
|
||||
|
||||
## Code Walkthrough
|
||||
|
||||
|
||||
|
||||
Walk through the code, one chunk at a time. Don’t belabor topics that have been discussed in earlier examples. Provide sample code, but don’t provide exhaustive explanations for how to program underlying platforms like HTML syntax unless there is something unique to the implementation.
|
||||
|
||||
An important thing to emphasize is that every interaction with the XRPL is either a transaction or a request, and that all transactions and requests are essentially the same. The sample code we provide shows how to prepare the transaction or request, and how to process the returned results. Knowing how to submit and respond to one transaction or request gives a pretty good idea for how to submit and respond to any transaction or request.
|
||||
|
||||
(Technically there is third category, similar to a request: a notification from a subscription stream. See [Subscription Methods](subscription-methods.html).)
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
|
||||
At the end of the tutorial, provide links to additional resources, conceptual information, and any tutorials that would be a sensible next step in the learning journey.
|
||||
Reference in New Issue
Block a user