json-schema-org
[📝 Docs]: Fuse documents and create a single comprehensive tutorial
What Docs changes are you proposing?
The information contained in Creating your first schema and The basics is repetitive. We will use the best parts of each document and create a single comprehensive beginner tutorial that is going to live in the new Introduction section of the new documentation structure - issue #790
Code of Conduct
- [X] I agree to follow this project's Code of Conduct
New proposed Outline for the fusing tutorial
Creating your first JSON Schema
Table of content
Background
- This section will reuse information in the introductory paragraphs of The Basics and Create your first schema tutorials.
Before you start
- This section will list every needed prerequisite
Introduction to JSON Schema
- This section will reuse information in the Introduction to JSON Schema from Creating your first schema and Hello World from The Basics.
Example
- This section would resume information in the overview section of (the product catalogue) Creating your first schema tutorial.
Creating a schema definition
- This section will reuse information in Creating a schema definition from Creating your first schema and Declaring a JSON Schema from The basics.
The type keyword
- This section will reuse information from the type keyword section of The Basics.
Define properties
- This section will reuse information in the Define Properties section of Creating your first schema.
Create a nested data structure.
- This section will reuse information in the Create a nested data structure of Creating your first schema.
Declaring a unique Identifier
- This section will reuse information in Declaring a unique identifier of The Basics.
Add an external reference
- This section will reuse information in the Add an external reference of the Creating your first schema.
Validate a JSON Schema
- This section will reuse information contained in the Validate a JSON Schema of the Creating your first schema
What next
- This section will reuse information in the What Next section of Creating your first schema.
N.B: This template was adapted from the TGDP tutorial template: https://gitlab.com/tgdp/templates/-/blob/main/tutorial/template-tutorial.md?ref_type=heads
What do you think? CC: @valeriahhdez @benjagm
todo: Organize the tutorial's content by heading/section and put which content you'll use inside each section. This will help visualize the final structure of the tutorial. For example: Bakcground This section will reuse information contained in the introductory paragraphs of The basics and Create your first schema tutorials.
suggestion: Use TGDP tutorial template: https://gitlab.com/tgdp/templates/-/blob/main/tutorial/template-tutorial.md?ref_type=heads Please remember to acknowledge the project if you do use it.
suggestion: Using TGDP template, you can leave the overview and let readers know this will be the result of the tutorial.
"In this tutorial, you'll learn to create a product catalog that stores its data using JSON objects, like the following:"
Thank you so much for the awesome feedback @valeriahhdez. Could you take a look at the updated version? Thank you.
Just a minor observation, no prerequisites are needed to create JSON schemas so you can remove the "Before you start" section
I suggest to be much more conservative with the proposal. The current getting started guide "Creating your first schema" has a lot of great content and I think is working fine. My proposal is to keep the "Creating your first schema" as the main content here and add the information that is missing compared with The basics... if there is any and then remove the basics page and create a redirect to the "Creating your first schema" page.
Regarding the new structure proposal: Do we need a Background(1) and Example(4) sections in the current getting started guide? I am not sure about it. I think we need to discuss this in a team meeting.
After some additional consideration I think we should not fuse these 2 pages. The basics page is not a guide and I think it plays a key role as introduction in the reference section before all the keywords sections.
As agreed in our last docs meeting, there was no need to fuse the Creating your first schema and The basics, so I will close this issue now.