[📝 Docs]: Fix documentation anomalies [UI/UX change]

[bhavukkalra]

What Docs changes are you proposing?

on the page getting-started-step-by-step we see a lot of anomalies in the numbering. For example -

and

CC - @benjagm @gregsdennis
Do let me know if they seem valid to be fixes and I can go ahead and create a PR for the same?

Code of Conduct

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

[github-actions]

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.

[bhavukkalra]

On a similar line of thought. Adding required keys "productId", "productName" was kinda confusing. The docs does mentions that they are required but it can't be observed in the changes made.
It is only some time later that we see the line of code

"required": [ "productId", "productName", "price]" 

Where it starts to make sense.

I think there is a better way to write it like this

• Add the required keyword product id by appending this

  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    }
  },

  "required": ["productId"]

TLDR - Update the required key as we go along adding new attributes. Not all at once (which is currently in the docs). As it makes a proper flow of what is written in text and simultaneously in code

[benjagm]

Thanks for sharing your findings. I think this issue should be divided into 2: one for the list numbering issues and another for the rest of comments regarding formatting, wording and snippets

[bhavukkalra]

Sure. Thanks for your inputs @benjagm. Created a new issue #658 for the snippets, wording change. In process of creating a PR for both soon.

[benjagm]

Once you have the issues created that way let's continue the discussion to complete the triage to move the issue to available status. That is the point when you can create the PR.

[gregsdennis]

I think the issue here is alignment of the code blocks. They should be indented so that the block appears as part of the numbering.

For example:

1. Some text here
    ```
    and then an indented code block
    ```
2. Another text block

Versus...

1. Some text here
```
and then a code block
```
2. Another text block

(Github seems to render the numbering correctly in both, but I'm not sure the website does.)

[benjagm]

This is how I fixed the the problem with the repeated formats:

8001fe3

It seems that it need to be one single new line between the list item and the code snippet. Instead of just fixing how I did we'll need to find the root cause.

[bhavukkalra]

Hey Thanks for that benjamin. It was a markdown issue after all. Found the root cause over here. markdown-continue-numbered-list.

It seems like markdown uses spacing between ordered lists pairs to determine if a code block is still inside the scope or not.
But yeah, We'll need to see how many more pages are there where this fix needs to be applied.