Revisit existing documentation

[qu1queee]

Per Grooming, we want to revisit the current docs in this repo. We are looking for:

• typos
• markdown linters warnings
• broken links

Aim is to keep our docs optimal, as they will serve as the source of truth for our website.

[avinal]

Hey @SaschaSchwarze0 I want to work on this issue. I have one suggestion on the line length, it is default at 80 chars using any markdownlint, for better readability, I propose to use either 100 or 120 chars. I will start working once we agree on this.

[SaschaSchwarze0]

Hey @SaschaSchwarze0 I want to work on this issue. I have one suggestion on the line length, it is default at 80 chars using any markdownlint, for better readability, I propose to use either 100 or 120 chars. I will start working once we agree on this.

Thanks @avinal for volunteering. Do we really have a line length limit in a markdown linter somewhere? I know them for code files, but for markdown? I am against any line limit in markdown as I prefer a paragraph to be a single line - editors like vscode can then dynamically line-break based on the window size.

We actually have long lines like https://github.com/shipwright-io/build/blob/main/docs/build.md?plain=1#L56C126-L57C1. I am using https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint as linter and that file is validated without any warnings.

[avinal]

There is no hard rule and yes, modern editors automatically wrap long lines. I will then ignore the line length limitation and fix the other linting issues.