The legacy documents should mention into superseded document

[ilsubyeega]

Describe the problem

For example. https://docs.flutter.dev/go/desktop-multi-window-support goes https://docs.google.com/document/d/11_4wntz_9IJTQOo_Qhp7QF4RfpIMTfVygtOTxQ4OGHY results 2020 last updated document, while newer https://flutter.dev/go/multi-window-api exist. This is confusing since google search index(docs.flutter.dev) shows the old documents at first.

https://docs.flutter.dev/search?q=multi+window

Expected fix

• old documents should mention the superseded document and append the suffix of the docs title something like superseded or finished etc.. (newer document mentions old ones, but it should bidirectional)
• search indexes at docs.flutter.dev might need to improved. i guess since it is forwarded via docs.flutter.dev/go/... so it was indexed but not sure about direction to index docs.

On which browser(s) did you experience this issue?

No response

Additional context

This was previously discussed in flutter discord(#hackers-).

I would like to fix this problem.

• I will try and fix this problem on docs.flutter.dev.

[sfshaza2]

@parlough, thoughts?

[parlough]

Thanks for the issue and discussion here!

This is a bit tricky. It's not always clear-cut that one design doc supersedes another. Perhaps they are alternative proposals for the same problem. Even once they aren't valid anymore, their go-link should continue working for reference and historical purposes.

What we can do is document and highly suggest updating old design docs when one is superseded as well as linking to alternative or updated proposals from design docs in general. It won't always be possible as the author might not be active anymore. If you think this would be valuable, can you open a focused issue for that discussion on the the flutter/flutter repository? These guidelines could either be mentioned in https://github.com/flutter/flutter/blob/main/docs/contributing/Design-Documents.md and/or the template itself (found at flutter.dev/go/template) could be updated.

I also suggest checking http://docs.flutter.dev/resources/design-docs, which is supposed to be a maintained list of active design docs on GitHub, instead of trying to use the Google-based search. We don't have much control over the Google-based search and plan to retire its usage eventually. That issue list should hopefully be more up to date and provide better filtering capabilities.