New spec page structure #819

kwennB · 2024-07-23T10:01:06Z

What kind of change does this PR introduce?

Documentation Enhancement

Issue Number:

Closes #___ [📝 Docs]: Implement the Spec restructuring (Docs Website) #791

Screenshots/videos:

Added

Summary

The Specification section of the docs is fixed to adapt to the proposed change in alignment with Diataxsis and issue #791

It fixes the spec navigation
Draft templates
Re-edits Release note page
Re-edits JSON hyper-schema page
Adds a Migration page

Does this PR introduce a breaking change?

No

gregsdennis

Please see my comment in the associated issue. I don't feel we should be reformatting these documents.

Blocking until that is resolved.

benjagm · 2024-07-23T22:22:15Z

Please see my comment in the associated issue. I don't feel we should be reformatting these documents.

Let's discuss this Greg. I asked the docs team to do this. I have strong arguments for this change.

gregsdennis · 2024-07-23T22:23:24Z

I agree it needs to be discussed. It never was. We should use the issue.

benjagm · 2024-07-23T22:33:43Z

I agree it needs to be discussed. It never was. We should use the issue.

This is part of the Google Season of Docs projects and the issue has been there for months.

My feeling is you think we are republishing, and we are just reorganizing and elevating our docs.

If you think we shouldn't add the draft publication details like authors in this page that is fine. We can change that and other things as per the community feedback.

We are going to reestructure the website docs....that is what the Docs strategy issue is about and why we applied to GSoD.

It appears I misunderstood the purpose of this issue. The specification documents themselves are not changing, only the specifications page.

benjagm

Hi Blessing. Great work wit this first PR.

I left some comments. Migration, JSON Hyper Schema and release notes need still a lot of work.

benjagm · 2024-07-23T22:58:09Z

components/DocTable.tsx

+                </Link>
+              </td>
+            </tr>
+            <tr className='dark:hover:bg-slate-950 hover:bg-slate-300 '>


Let's remove this implementations section for now. When it is ready, we can add a link to the new tooling page.

benjagm · 2024-07-23T23:00:36Z

pages/draft/2020-12/index.md

+type: docs
+authors: ['Austin Wright', 'Henry Andrews', 'Ben Hutton', 'Greg Dennis']
+Metaschema: 'https://json-schema.org/draft/2020-12/schema'
+Implementations: 'https://bowtie.report/#/dialects/draft2020-12'


Lets remove the implementations metadata from here.

benjagm · 2024-07-23T23:01:02Z

pages/draft/2020-12/index.md

+Metaschema: 'https://json-schema.org/draft/2020-12/schema'
+Implementations: 'https://bowtie.report/#/dialects/draft2020-12'
+Specification: 'https://json-schema.org/draft/2020-12/json-schema-core.html'
+Status: 'Stable'


Let's remove the status field as well.

benjagm · 2024-07-23T23:02:29Z

pages/draft-06/index.md

+authors: ['Austin Wright', 'Henry Andrews', 'Ben Hutton', 'Greg Dennis']
+Metaschema: 'https://json-schema.org/draft/2020-12/schema'
+Specification: 'https://json-schema.org/draft/2020-12/json-schema-core.html'
+Implementations: 'https://bowtie.report/#/dialects/draft2020-12'


Let's remove implementations and status details from all the drafts

benjagm · 2024-07-24T06:14:11Z

pages/draft/2020-12/index.md

+- **Embedded Schemas and Bundling**: Provides guidance on bundling schemas into a Compound Schema Document.
+- **Vocabulary Changes**: Separates the `format` vocabulary into `format-annotation` and `format-assertion`.
+
+### Access all data connected to Draft 2020-12


I suggest calling this section just "Draft 2020-12 Documents"

benjagm · 2024-07-24T06:27:22Z

pages/migration/index.md

This page needs more work. We should call out here Alterschema https://github.com/sourcemeta/alterschema as the tool to help with the migration to newer schemas. Please speak with @jviotti (TSC member). He is probably the best person the speak with to create here a new great page.

Check examples in other languages like: https://www.asyncapi.com/docs/migration/migrating-to-v3

benjagm · 2024-07-24T06:31:56Z

pages/json-hyper-schema/index.page.tsx

This page requires work as well. I think it requires an introduction, all the links and finally the release notes.

We should update the sidebar to add all the child pages.

The JSON-hyper-schema page cannot carry all the release notes. What would be the usefulness of the release notes page?

I agree with having an introduction and updating the sidebar to carry all child pages. When you say 'all the links' - all the hyper-schema links, yes?

benjagm · 2024-07-24T06:33:02Z

pages/release-note/index.page.tsx

@@ -0,0 +1,46 @@
+import React from 'react';


Folder name should be release-notes

benjagm · 2024-07-24T06:36:05Z

pages/release-note/index.page.tsx

+import StyledMarkdown from '~/components/StyledMarkdown';
+import { SectionContext } from '~/context';
+
+export async function getStaticProps() {


This pages needs a lot of work. I'll try to push some code later today.

benjagm · 2024-07-24T06:37:29Z

components/DocTable.tsx

@@ -0,0 +1,78 @@
+import React from 'react';


Can we refine the style of the table to be similar to this one (@DhairyaMajmudar )

https://developer.android.com/about/versions/15/release-notes?hl=es-419

looking forward for the change : )

kwennB requested a review from a team as a code owner July 23, 2024 10:01

kwennB mentioned this pull request Jul 23, 2024

[📝 Docs]: Implement the Spec page restructuring (Docs Website) #791

Closed

1 task

kwennB requested review from valeriahhdez, benjagm and DhairyaMajmudar July 23, 2024 10:06

gregsdennis previously requested changes Jul 23, 2024

View reviewed changes

benjagm requested changes Jul 24, 2024

View reviewed changes

benjagm added 📝 Documentation Indicates improvements or additions to documentation. Status: In Progress This issue is being worked on, and has someone assigned. labels Jul 24, 2024

kwennB closed this Jul 24, 2024

gregsdennis changed the title ~~New spec structure~~ New spec page structure Jul 24, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New spec page structure #819

New spec page structure #819

kwennB commented Jul 23, 2024

gregsdennis left a comment

benjagm commented Jul 23, 2024

gregsdennis commented Jul 23, 2024

benjagm commented Jul 23, 2024 •

edited

Loading

benjagm left a comment •

edited

Loading

benjagm Jul 23, 2024

benjagm Jul 23, 2024

benjagm Jul 23, 2024

benjagm Jul 23, 2024

kwennB Jul 24, 2024

benjagm Jul 24, 2024

benjagm Jul 24, 2024

benjagm Jul 24, 2024

kwennB Jul 24, 2024

benjagm Jul 24, 2024

benjagm Jul 24, 2024

benjagm Jul 24, 2024

DhairyaMajmudar Jul 24, 2024

New spec page structure #819

New spec page structure #819

Conversation

kwennB commented Jul 23, 2024

gregsdennis left a comment

Choose a reason for hiding this comment

benjagm commented Jul 23, 2024

gregsdennis commented Jul 23, 2024

benjagm commented Jul 23, 2024 • edited Loading

benjagm left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjagm commented Jul 23, 2024 •

edited

Loading

benjagm left a comment •

edited

Loading