Addressing suggestions for enhanced documentation #19
Description
Original 2025-07-17 question from feedback spreadsheet: Matt suggests focusing on expanding and improving the project documentation—such as the GitHub repo or read-the-docs page—over the next few months to clearly demonstrate its value and utility to users, which is crucial for the project's success.
Initial PRC response: David agrees documentation should be improved, including adding a summary diagram for clarity. Peter adds they plan to keep documentation lightweight using markdown in GitHub rather than more complex tools like Read the Docs to maintain simplicity and focus.
My remaining questions/concerns: It doesn't seem like any significant enhancements to documentation has been made - to include suggestions around describing think like: (1) use cases (2) what implementation looks like in practice, (3) implementation guidance around how adopters can apply it (4) examples of its application in practice, (5) future plans for expanding/evolving the spec.
One easy win would be leveraging the existing slide deck and presentation recording, which has lots of good material for better documenting the spec. Minimally this material should be linked from the README. But even better, build material from this and other suggested topics into a simple and focused RTD site. This would provide a central hub for all user-facing documentation outside of the scattered github readmes (which aren't best suited to serve as public documentation).
Just my 2c - I know the spec is simple and early in its development - so not a lot of documentation is needed. But I think some of the suggestions above would be easy to implement, and add value/clarity.