Open ssteinbuss opened 1 month ago
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.
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.
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:
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
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:
Thank you for your contributions and support. We look forward to your proposals and working together to improve our project documentation!