Policy for outdated documents in the repo #1349
Comments
|
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. |
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.
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. |
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. |
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 |
|
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. |
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. |
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. :-) |
|
Right, sorry, I meant this repo ( |
|
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:
|
|
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.) |
|
Ah, oops, I misunderstood. Sorry! |
|
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? |
As per WebAssembly/design#1349, we don't want to keep most of the design docs at the top level as they're out of date. Rather than getting rid of all of them at once, I've set up redirects for design docs that have explicit up-to-date versions (such as Binary Encoding, Text Format, Semantics, etc.), as well as for couple of docs that are no longer of interest - for those I'm redirecting to Markdown files in the original repo just so that URLs keep working. For a few docs still under the question of whether they should be pointing to better resources or updated themselves, I'm currently keeping them in the sidebar, but merging Docs & FAQ sections together to reduce the clutter.
|
@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. |
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.
The text was updated successfully, but these errors were encountered: