[📝 Docs]: Improve documentation's information architecture

[valeriahhdez]

What Docs changes are you proposing?

This issue addresses an item of Release 4 of the Documentation strategy execution [Issue #158]. More specifically, it improves the information architecture of the current documentation, which aligns better with the documentation developer journey and organizes content based on the diataxis framework.

Below is a summary of the main changes to the current structure.

1. The documentation will be organized into the following content buckets:

• Introduction
• The basics
• Guides
• Reference
• Specification

2. The getting started will be renamed as The basics.

3. Some documents will be relocated to the new sections.

4. We will change the tile of some pages to better convey the type of document they are:

• Starting with a verb for guides.
• Starting with nouns for reference documents.

5. Each content bucket will have an Overview page.

See the full proposal.

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[github-actions[bot]]

Welcome to the JSON Schema Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look to our contributors guide if you plan on opening a pull request. For more details check out README.md file.

[benjagm]

Thanks Valeria. Is this going to be all in one PR?

[valeriahhdez]

The Google spreadsheet (linked in this issue) contains changes to the information architecture and news documents that will be produced. Following our last meeting, the scope of the PR for this issue is limited to the structural changes of the new information architecture. We will create GitHub issues for the missing documents and these will be linked to this issue.

[benjagm]

I have some doubts regarding the proposed introduction and concepts sections.

I really like Option 1 provided in the Figma file, I don't see the benefits of option 2.

• Introduction is a section expected to provide high-level information about the initiative, and not cover getting started guides...
• Why having to choose between concepts and guides? For me is clear that we need a section called guides to provide the getting started guide and access to the "Tour of JSON Schema". In addition we can discuss about what to do with the Glossary, keeping it into the reference section or create a separate concepts section. At this point I suggest keeping the glossary page inside the reference as a standalone page as it is today.

[valeriahhdez]

Closing this issue as the proposed changes are no longer applicable to recent documentation website improvements.

[benjagm]

We still need to implement option 1 right?

[valeriahhdez]

In my opinion, most changes option 1 proposed have already been implemented in the last changes. For example, I don't think we need to add a Community section to the docs page because it already has its own page and is shown in the top menu. Maybe when we create more resources, for example to use Bowtie, we can create the Resources section. We can talk about this at our next meeting.

[benjagm]

Hi @valeriahhdez . As we just discussed I am reopening this issue to work in the sidebar restructuring.

[benjagm]

@valeriahhdez Can you please create a new issue just with a clear explanation of what are the changes to be made in the sidebar? Please write the issue in such a way a developer with no context about the docs strategy can proceed with the changes:

For example:

• Explaining the changes in the sidebar. Including node titles, new items, items to be removed, and changes in the hierarchy
• Explaining the changes in the title of pages
• Explaining the pages to be removed
• The new intro pages are to be created, including examples.

I have been trying to find time for it but after 2 months it is being impossible.

Thanks a lot!!

[valeriahhdez]

@valeriahhdez Can you please create a new issue just with a clear explanation of what are the changes to be made in the sidebar? Please write the issue in such a way a developer with no context about the docs strategy can proceed with the changes:

For example:

• Explaining the changes in the sidebar. Including node titles, new items, items to be removed, and changes in the hierarchy
• Explaining the changes in the title of pages
• Explaining the pages to be removed
• The new intro pages are to be created, including examples.

I have been trying to find time for it but after 2 months it is being impossible.

Thanks a lot!!

Done. Let me know if anything needs further clarification.

[harshita9104]

**Sidebar Structure

1. Rename Content Buckets** Overview → Introduction (to better reflect its purpose as the starting point). Getting Started → Quick Start (a more action-oriented and concise label).
2. Add a New Content Bucket: "Guides" Relocate practical and example-based documents (currently scattered) to a new Guides section. Examples: "Tour of JSON Schema" (from Getting Started). "Examples" subcategory (e.g., "Miscellaneous examples," "Modeling a file system"). II. Improved Document Grouping and Relocation
3. Introduction Keep the following at the top as they are crucial for new users: "What is JSON Schema?" "Roadmap" "FAQ" Group additional general resources (e.g., "Sponsors," "Use Cases") under a Resources subheading.
4. Quick Start Relocate beginner-friendly content from Reference to Quick Start to create a seamless learning path: "What is a schema?" "JSON Schema glossary" Rename "Creating your first schema" → "Create your first schema" for consistency.
5. Guides (New Bucket) Create a focused section for practical and example-based learning: Relocate "Tour of JSON Schema" from Getting Started. Include all examples like "Miscellaneous examples," "Modeling a file system," and "Other examples." Add a "Common use cases" guide to showcase real-world applications.
6. Reference Organize into logical subcategories: Keywords: Group all type-specific and generic keywords together. Example: "String," "Numeric types," "Boolean," "Annotations," etc. Schema Features: Group advanced topics like: "Conditional schema validation" "Boolean JSON Schema combination" "Modular JSON Schema combination" Implementation: Add "Common interfaces across implementations" under this heading. III. Style Enhancements
7. Title Standardization Change all page titles to sentence case for consistency: Examples: "JSON Schema Glossary" → "JSON Schema glossary" "Creating your first schema" → "Create your first schema" "Applying subschemas conditionally" → "Conditional schema validation"
8. Add Overview Pages Include an Overview page for each bucket summarizing its content. Example: Reference Overview briefly explains the types of keywords, schema features, and implementation details.

[harshita9104]

Hello @valeriahhdez @benjagm ,

Kindly assign me this issue!

Thank you

[valeriahhdez]

Hi @harshita9104,,

This issue has already been assigned and is in progress. To find issues you can claim, please check the "labels" section shows "available" and that no one has been assigned to the issue. Thank you.