(WIP) Revised tutorial structure/template #3230

mDuo13 · 2025-08-12T01:53:21Z

Update "Tutorial Guidelines" with more specific, actionable guidelines for making tutorials. ⇒ Preview
- Known issue: I haven't deleted the old screenshots yet, but that should happen before merging this (if we're going to go through with it)
Rewrite the Tutorial Structure page into a Tutorial Template, representing the best practices for how tutorials should work. ⇒ Preview
Refactor the verify_credential.js code sample into a linear script that is much less powerful but much simpler, as a demonstration of the guidelines for code samples. This is somewhat experimental and should be used as a point of comparison to confirm if this is really the direction we want to go with code samples & tutorials in general.
- Compare: Current verify_credential.js vs Revised verify_credential.js
- Known issue: The existing tutorial still needs to be updated to reflect the new code sample. Probably, some of the examples from the usage section should be moved to the README. (You have to edit the hard-coded values instead of passing them on the commandline now.)

resources/contribute-documentation/tutorial-guidelines.md

oeggert · 2025-08-15T18:33:53Z

resources/contribute-documentation/tutorial-guidelines.md

-1. Sample code snippets they can copy and paste into their own applications.
-2. Complete API reference documentation.
+- Developers can copy and paste the sample code into their own applications.
+- Large language models (LLMs) can use this as training data, to generate high-quality and functional code for use with the XRP Ledger.


Suggested change

- Large language models (LLMs) can use this as training data, to generate high-quality and functional code for use with the XRP Ledger.

- Large language models (LLMs) can use this as training data to generate high-quality code for use with the XRP Ledger.

oeggert · 2025-08-15T18:35:49Z

resources/contribute-documentation/tutorial-guidelines.md


-Modular tutorials follow Malcolm Knowles’ six assumptions for designing adult learning:
+LLMs are increasingly being used in software development, for example in tools that can generate code based on natural-language descriptions. To assist users of these tools, we would like to provide many working code samples that demonstrate best practices and follow consistent structure and style. Tutorials that have descriptions of what the code does alongside matching code snippets help LLMs develop the correct associations between terms used in natural language and programming language, hopefully leading to more accurate results from code generation.


Suggested change

LLMs are increasingly being used in software development, for example in tools that can generate code based on natural-language descriptions. To assist users of these tools, we would like to provide many working code samples that demonstrate best practices and follow consistent structure and style. Tutorials that have descriptions of what the code does alongside matching code snippets help LLMs develop the correct associations between terms used in natural language and programming language, hopefully leading to more accurate results from code generation.

LLMs are increasingly being used in software development. To assist users of these tools, we would like to provide many working code samples that demonstrate best practices and follow consistent structure and style. Tutorials that have descriptions of what the code does alongside matching code snippets help LLMs develop the correct associations between terms used in natural language and programming language, hopefully leading to more accurate results from code generation.

oeggert · 2025-08-15T18:49:10Z

resources/contribute-documentation/tutorial-guidelines.md


-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 should be provided in the `_code-samples/` folder at the top of this website's source repository, with separate subfolders by programming language. There should be a `README.md` file for each code sample _above_ the language folders describing what the code sample does in general, _and_ a `README.md` in each programming language folder describing how to install and run that code sample specifically.


Suggested change

Sample code should be provided in the `_code-samples/` folder at the top of this website's source repository, with separate subfolders by programming language. There should be a `README.md` file for each code sample _above_ the language folders describing what the code sample does in general, _and_ a `README.md` in each programming language folder describing how to install and run that code sample specifically.

Sample code should be organized by functionality in the [_code-samples/](TBD) repository, with subfolders for each programming language. Include a `README.md` in the code sample folder describing what the code samples do in general, _and_ a `README.md` in each programming language folder describing how to install and run that code sample specifically.

Place holder until code samples moved to submodule repo.

oeggert · 2025-08-15T18:52:57Z

resources/contribute-documentation/tutorial-guidelines.md


-## Concepts
+Use comments to separate out logical sections of the sample code. You can these comments as markers so that the `{% code-snippet ... %}` Markdoc component shows only the relevant section at a time in a tutorial.


It might be worth having a small section documenting all our tags. Maybe not in this page, but a separate reference page we can link to?

+1 on documenting all our tags, definitely needed.

oeggert · 2025-08-15T18:55:12Z

resources/contribute-documentation/tutorial-guidelines.md


+Some legacy tutorials show example requests and responses using WebSocket or JSON-RPC APIs, sometimes using the `rippled` commandline. These are not recommended, for the following reasons:


Suggested change

Some legacy tutorials show example requests and responses using WebSocket or JSON-RPC APIs, sometimes using the `rippled` commandline. These are not recommended, for the following reasons:

Some legacy tutorials show example requests and responses using WebSocket, JSON-RPC APIs, or the `rippled` commandline. These are not recommended, for the following reasons:

oeggert · 2025-08-15T21:24:12Z

resources/contribute-documentation/tutorial-template.md

+
+You can find the complete source code for this tutorial's examples in the {% repo-link path="resources/contribute-documentation/tutorial-structure.md" %}resources section of this website's repository{% /repo-link %}.
+
+{% admonition type="success" name="Tip" %}
+Use the `{% repo-link ... %}` component to link to the source files; this component is designed to adjust based on the environment, so for example previews link to the code on the preview branch... although it doesn't fully work as of this writing (2025-08-11).
+{% /admonition %}


Suggested change

You can find the complete source code for this tutorial's examples in the {% repo-link path="resources/contribute-documentation/tutorial-structure.md" %}resources section of this website's repository{% /repo-link %}.

{% admonition type="success" name="Tip" %}

Use the `{% repo-link ... %}` component to link to the source files; this component is designed to adjust based on the environment, so for example previews link to the code on the preview branch... although it doesn't fully work as of this writing (2025-08-11).

{% /admonition %}

Use the `{% repo-link ... %}` component to link to the source files; this component is designed to adjust based on the environment, so for example previews link to the code on the preview branch... although it doesn't fully work as of this writing (2025-08-11).

Doesn't feel great to tell someone to use a tag and in the same breath say it doesn't work. How big of a lift is it to fix that component?

oeggert · 2025-08-15T21:25:35Z

resources/contribute-documentation/tutorial-template.md

+To test that the code runs properly, you can navigate to the repository top and start the local Redocly server as follows:
+
+```sh
+npm run start
+```
+
+Then, navigate to <http://localhost:4000/resources/contribute-documentation/tutorial-structure> to view the parsed version of this page.
+
+{% admonition type="info" name="Usage is optional" %}
+You should include a Usage section in **sample app tutorials**. Provide a "Usage" section if this tutorial's sample code:
+- Has a GUI with multiple buttons/inputs
+- Is a commandline utility with multiple options/parameters
+- Consists of multiple scripts that need to be run in a specific order
+
+If there's a user interface, you can also embed a video demonstrating usage of the sample app.
+
+For single-file scripts that perform a linear set of steps without user input, omit the Usage section.
+{% /admonition %}


Like the previous sections, the admonition info feels like the actual instructional part we want to be the focus. Maybe we move the "example" text into the admonition block instead?

oeggert · 2025-08-15T21:27:54Z

resources/contribute-documentation/tutorial-template.md

+{% /tab %}
+{% /tabs %}
+
+### 2. Connect and get account(s)


Suggested change

### 2. Connect and get account(s)

### 2. Connect and get account(s)

I get we're trying to show a real example header here, but it feels a little confusing to have the header not match the content of the step. I think it'd be better to match the header to the content, in this case: 2. Label step headings

oeggert · 2025-08-15T21:28:28Z

resources/contribute-documentation/tutorial-template.md

+Most code samples need at least one account. The first step should generally cover from the start of the file (including imports) through instantiating a client, connecting to a network, and deriving wallets and/or funding accounts via the faucet.
+
+{% tabs %}
+
+{% tab label="JavaScript" %}
+{% code-snippet file="/_code-samples/verify-credential/js/verify_credential.js" language="js" before="// Look up Credential" /%}
+{% /tab %}
+
+{% /tabs %}
+
+{% admonition type="info" name="Code snippets and steps" %}
+Each "step" of the tutorial should correspond to one code snippet (with tabs by programming language). There can be exceptions, for example if one programming language needs additional code in a separate place to make the same functionality work.
+{% /admonition %}


Make this a separate step (3. Code guidelines), assuming we follow the previous suggestion of breaking steps out as the "instructions" of this tutorial.

oeggert · 2025-08-15T21:30:03Z

resources/contribute-documentation/tutorial-template.md

+Use `{% code-snippet ... %}` tags instead of copy-paste to display the code samples, so that you don't have to manually keep the code in the doc synchronized with changes to the code sample. To facilitate this, use `from=` and `before=` strings based on unique comments in the code. The first code snippet should omit `from=` and the last should omit `before=`.
+
+{% tabs %}
+
+{% tab label="JavaScript" %}
+{% code-snippet file="/_code-samples/verify-credential/js/verify_credential.js" language="js" from="// Credential has passed all checks" /%}
+{% /tab %}
+
+{% /tabs %}


Move this into the proposed step 3 above.

mDuo13 added 2 commits August 11, 2025 16:20

Draft revised tutorial structure/template

0d81c67

Revise tutorial guidelines

58b2b5b

maria-robobug reviewed Aug 12, 2025

View reviewed changes

resources/contribute-documentation/tutorial-guidelines.md Show resolved Hide resolved

maria-robobug reviewed Aug 12, 2025

View reviewed changes

resources/contribute-documentation/tutorial-guidelines.md Outdated Show resolved Hide resolved

maria-robobug reviewed Aug 12, 2025

View reviewed changes

resources/contribute-documentation/tutorial-guidelines.md Show resolved Hide resolved

Add env var as an option for secret keys

e5d261e

mDuo13 mentioned this pull request Aug 13, 2025

Add sample code for XLS-89d MPT Metadata #3233

Open

mDuo13 added 2 commits August 13, 2025 13:46

Revise tutorial template per feedback

39cb3de

Update tutorial guidelines per review

23661ce

oeggert reviewed Aug 15, 2025

View reviewed changes

mDuo13 mentioned this pull request Aug 16, 2025

Show two possible formats of Escrow sample code #3241

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

(WIP) Revised tutorial structure/template #3230

(WIP) Revised tutorial structure/template #3230

mDuo13 commented Aug 12, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

maria-robobug Aug 18, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

oeggert Aug 15, 2025

Uh oh!

Uh oh!

	- Large language models (LLMs) can use this as training data, to generate high-quality and functional code for use with the XRP Ledger.
	- Large language models (LLMs) can use this as training data to generate high-quality code for use with the XRP Ledger.


		Modular tutorials follow Malcolm Knowles’ six assumptions for designing adult learning:
		LLMs are increasingly being used in software development, for example in tools that can generate code based on natural-language descriptions. To assist users of these tools, we would like to provide many working code samples that demonstrate best practices and follow consistent structure and style. Tutorials that have descriptions of what the code does alongside matching code snippets help LLMs develop the correct associations between terms used in natural language and programming language, hopefully leading to more accurate results from code generation.


		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 should be provided in the `_code-samples/` folder at the top of this website's source repository, with separate subfolders by programming language. There should be a `README.md` file for each code sample _above_ the language folders describing what the code sample does in general, _and_ a `README.md` in each programming language folder describing how to install and run that code sample specifically.


		## Concepts
		Use comments to separate out logical sections of the sample code. You can these comments as markers so that the `{% code-snippet ... %}` Markdoc component shows only the relevant section at a time in a tutorial.


		Some legacy tutorials show example requests and responses using WebSocket or JSON-RPC APIs, sometimes using the `rippled` commandline. These are not recommended, for the following reasons:

	### 2. Connect and get account(s)
	### 2. Connect and get account(s)

(WIP) Revised tutorial structure/template #3230

Are you sure you want to change the base?

(WIP) Revised tutorial structure/template #3230

Conversation

mDuo13 commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mDuo13 commented Aug 12, 2025 •

edited

Loading