Repository navigation
Does the spec make the older docs redundant? #148
Description
Having briefly discussed some problems with docs/design/Modules.md with @lukewagner (#147), he suggested just deleting the doc as it's old, unmaintained and incorrect in many places. I asked for it to stay up, as there isn't much information at that level of detail currently (it's all either intros or specs).
Luke helped me with my problem, and suggested editing Modules.md to improve it, which I was happy to do, but I'm totally new to WASM, and the doc is far more out of date than I realized, so I'm not confident that what I've written is current and correct.
I'll attach my version of Modules.md, in case anyone wants to help with it:
Modules.txt
More generally, there's a lack of detailed information about WAT and WASM (other than the spec). I'd be happy to contribute to the documentation once I understand things better myself, but if the old docs have been abandoned in favor of the spec, are there any official docs to contribute to any more?
I'm happy to publish unofficial stuff on my own initiative, but wondered what the policy is. Is there a commitment to maintaining official documentation (other than the spec) now?
Activity
carlsmith commentedon Sep 18, 2019
I'm steadily figuring WASM out, so should be able to fix Modules.md by myself before very long, and I'm keen to contribute to the docs more generally over time (but don't want to make any concrete commitments up front).
If there's no intention to maintain the docs, I can always pillage them for content, and contribute to the broader ecosystem. It's cool either way. I just wondered what the plan is.
lukewagner commentedon Sep 18, 2019
It's possible folks just don't have a strong opinion on this. Since you found the docs helpful, that's perhaps a sign that it's worth updating them. @rossberg @dtig @dschuff ?
dtig commentedon Sep 18, 2019
In general I agree that keeping documentation up to date is a good idea, but in this case I'm concerned about setting expectations that the documentation in the design repository will stay up to date with spec changes as there isn't really a good way to make sure that that will happen. To avoid confusion, it might be a good idea to add a disclaimer saying the documentation is out of date like we do in JS.md.
rossberg commentedon Sep 19, 2019
@dtig makes a good point. Either we would have to get a reliable process into place for keeping old design docs up-to-date, or we should clearly mark them as "historic" and leave them as is for historic reference. I'm not sure how realistic the former is.
Moreover, design docs are not typically written as documentation -- they serve a different purpose and tend to be structured in a different manner. Just consider all the new proposals: the sum of their incremental descriptions will hardly provide a coherent and accessible documentation of the overall language down the line.
lukewagner commentedon Sep 19, 2019
I'm open to that too (my initial reaction being to just delete the old docs, but, channeling JF, deleting history is bad). Should we then additionally (1) remove their links from webassembly.org, (2) move them to some "/historical-archive" subdir of the design repo?
carlsmith commentedon Sep 20, 2019
Thanks for considering the issue.
It would be helpful to know the general scope of
webassembly.org, in terms of what it does and does not (aim to) document, and how (at what level et cetera).How much of the Docs section is going to be retained (when the design docs are removed)? The docs make up a large chunk of the site's content (and burden).
It may make sense to limit the scope to a central hub for the most important information (which is already adding up), so anything that can go on MDN et cetera should.
RReverser commentedon Jun 17, 2020
This is definitely something I'm going to be cleaning up now that I'm working on the website, and so far the idea is that none of the design docs will be listed in the sidebar.
Instead, we now have them linked from https://webassembly.org/specs/ as historical design docs.