WebAssembly
Policy for outdated documents in the repo
As per @rossberg, we have quite a few outdated documents in the repo. Should we revise them and possibly move to a folder or a separate repo or remove altogether?
Many are linked to from webassembly.org, which I'm now working on updating, and already set up redirects for obviously outdated documents like Binary Encoding, Text Format, Semantics and few others to their up-to-date counterparts on the spec repo.
Would it be ok to remove these outdated versions from this repo now to avoid confusion or are there more places that link out to them? Also same question, but for other docs as well.
IIRC, the CG recently discussed the feasibility of trying to keep the design docs up to date, and it wasn't clear how to do that unless we can find a dedicated long-term owner for that task. It would be a lot of work, since that person would have to integrate all the proposal docs in some way or the other.
That said, I don't think we should remove any docs from this repo, even if they are out of date. They still have value as the original design docs that provide all the rationale, for example. But we should mark them properly as such.
But we should mark them properly as such.
I think there's a value in moving them to a subfolder or something so that people who come across the repo for up-to-date information are not distracted by MVP one. However, the question of whether anyone is linking out to the existing docs remains.
That said, I don't think we should remove any docs from this repo, even if they are out of date.
Does this apply even to docs mentioned above like Binary Encoding, Text Format, Semantics that live in the spec repo now? Their historical versions can always be viewed via Git anyway, and for the most recent version spec repo seems like a better place.
Does this apply even to docs mentioned above like Binary Encoding, Text Format, Semantics that live in the spec repo now?
Yes, I think so. Not everybody is prepared to dig through git logs to find documents. And somebody may want to link to them -- GH doubles as a source repo and a web site here. So I think it would be nice to have a frozen version of the original docs somewhere on it. Some subfolder is totally fine, of course.
Not everybody is prepared to dig through git logs to find documents.
Sure, but a counter-argument can be that not everyone will need them. Given that latest version of these specs is a strict backward-compatible superset of what was there before, what is the usecase that would warrant preserving MVP-time snapshots?
Moreover, if it's just the digging aspect, we could add an mvp Git tag on the spec repo that anyone could jump to if necessary (or refer people to existing one like wg-1.0).
Don't assume that everybody coming to this site for information knows their way around git or GitHub. ;)
As somebody interested in PL history, I think historic documents have a value in themselves, and it's often sad that it's so difficult to come by first-hand documents. If we remove them here we should continue hosting them elsewhere. But this seems like a natural place.
Don't assume that everybody coming to this site for information knows their way around git or GitHub. ;)
Ha, I definitely assumed that. If not, we can include a link in the README that points directly to the necessary branch.
@RReverser I agree that it would be nice to make the out-of-date design documents less prominent. But when this has come up in the past, we've always decided to keep them as-is, both for historical reasons and due to incoming links. I'd be OK moving them somewhere else, as long as there were some way to handle redirects. But failing that, I think we should continue to mark the documents as out-of-date, but leave them where they are.
we've always decided to keep them as-is, both for historical reasons and due to incoming links
Right, I guess that's the main blocker for all other discussions / decisions. Do we know how many visits to these docs we still get aside from webassembly.org (which now redirects to up-to-date versions)?
This information should be available to Github admins on the repo, but I'm not one of them :)
@RReverser Looks like you were a "maintainer" before, I switched you to an "admin" of https://github.com/webassembly/website. :-)
Basically, as a maintainer, you should be able to go to https://github.com/WebAssembly/design/graphs/traffic and see basic stats on which Markdown docs are opened, which sites people are coming from to the Github repo etc. I don't have access to that, but it might be valuable for this sort of conversations.
Oh, of course. Whoops! Here's what I see for "Popular Content", on the traffic page:
| Content | Views | Unique visitors |
|---|---|---|
| WebAssembly/design: WebAssembly Design Documents | 633 | 430 |
| design/MVP.md at master | 449 | 365 |
| Proposal: Await · Issue #1345 | 400 | 104 |
| Will there be a JS -> WASM compiler? · Issue #219 | 373 | 326 |
| Issues | 251 | 68 |
| 设计/Rationale.md掌握·WebAssembly /设计 | 236 | 185 |
| design/Semantics.md at master | 232 | 123 |
| design/FutureFeatures.md at master | 187 | 140 |
| design/Nondeterminism.md at master | 186 | 164 |
| does support for socket(udp and tcp)? · Issue #1251 · WebAssembly/design · Gi... | 154 | 132 |
Like @rossberg, I've found that for research purposes it's really useful when languages and systems have versioned documentation available in accessible (and citeable) forms. That said, generally I want all the major versions, not just the initial version. So, if I were a researcher not in the CG, what I would find ideal is to have a subfolder with a snapshot of at least the specs for each "major" version, which maybe corresponds to each time a proposal advances to Phase 5. (For comparison, I use this page all the time, and I wish more systems had something like it.)
@RossTate, I agree, though it should be noted that the Java specs you link to correspond more to what's in the spec repo, whereas the current discussion is about design docs, which aren't really versioned. (Not sure if any design docs are publicly available for Java, I would sure love to see them.)
Ok, sounds like moving to a subfolder is the best compromise that we can all agree on. Would someone want to either make a PR or help me with identifying documents which are not as relevant for the current development?
@RReverser AFAIK, none of the documents are relevant anymore, aside from as a historical artifact. But I'm not sure we've agreed that they should be moved to a subdirectory. Is there a reason we need to move them? It doesn't seem like anyone wants to use the design repo for anything else, aside from discussion. My only concern is folks stumbling on to the documents and thinking they're up-to-date, but we have resolved that by adding a disclaimer to the top of the document.
@binji Primary reason for me is that webassembly.org uses list of Markdown files in this repo to populate Docs.
I'm currently split between two approaches to modernizing it: I can either remove that list altogether from the website so that it doesn't confuse newcomers (we already have a dedicated a link under "Specs" now), or, if some docs are still relevant, I can move the older ones to a subfolder here, so that only relevant docs would be rendered.
In either approach, I don't really want to manually track which docs are still relevant on the website side. If you're saying that none of them are, then I'd probably go with first approach and just not render this list at all.
I see what you mean. Personally I don't think any docs here should be surfaced on webassembly.org, so it's probably better to remove. Maybe others disagree, though.
Agreed with @binji. Where we link them from the org page it should likewise be made clear that these are historical docs.
How about things like "Portability", "Security" and "Nondeterminism in WebAssembly" and perhaps "Use Cases"? These seem still relevant, but if they are out of date, are there better resources to link to?
@RReverser Those ones all seem pretty good to me. I don't know that there are better resources, so I think it's OK to keep those.