Provide Specification Document as a Website

[ssteinbuss]

To improve the accessibility and usability of our specification document, it would be highly beneficial to provide it as a website, similar to the IDSA GitBook approach. This would allow contributors and users to easily navigate and find the information they need in a structured and user-friendly format. The website shall use neutral branding.

We are seeking proposals on the best way to achieve this goal.

Proposed Solution

Select a Documentation Framework: Identify a suitable framework or tool for generating and hosting the documentation as a website. Popular options include:

• GitHub Pages
• Read the Docs
• MkDocs
• Docusaurus

Set Up the Documentation Website: Implement the chosen framework/tool and deploy the documentation as a website. Ensure it is hosted on a reliable platform and is easily accessible to all contributors and users.

Action Items

• [ ] Gather proposals and suggestions for the best framework or tool to use for the documentation website.
• [ ] Select the most suitable option based on community feedback and project requirements.
• [ ] Set up and deploy the documentation website.
• [ ] Update the README and CONTRIBUTING documents to include links to the new documentation website.

Call for Proposals

We are inviting all contributors to propose their ideas and suggestions for how we can best provide our documentation as a website. Please share your thoughts on:

• The framework or tool you recommend and why.
• How to structure and organize the documentation for optimal usability.
• Any additional features or considerations to enhance the documentation website.

Thank you for your contributions and support. We look forward to your proposals and working together to improve our project documentation!

[arnoweiss]

I'd like to throw respec in the ring. It's an html-based tool that makes definitions and references way easier and renders into a w3c-like look. Tooling and docs are great.

I'd even argue that we can use it in a ISO-like way. ISO appears to exclusively use MS-Word-based tooling which is at conflict with this issue's very purpose. Our best option is probably using spec to imitate the ISO-template. I can offer to contribute here.

[ssteinbuss]

Indeed, this issue is only about creating HTML output and make it available via the web. In this sense respec looks like a reasonable tool. What I see from the respec documentation is that it is closely aligned with the structure of w3c documents. Our specification document shall be aligned with the ISO house rules on structure and formatting. I am fine with respec, if we can adapt the ISO rules easily.

The generation of an MS Word document afterward does not need to be considered here. This can be done manually or utilizing a tool like pandoc to convert markdown to word with the ISO template file.