Proposal: Guidance on link within samples

[dandhlee]

Description

At the moment, we have no guidance on providing links to other sources within the samples. While they're extremely valuable to have, it can hinder readability of the entire snippet as there would be horizontal scrollbars and other rendering issues such as rendering a long link on the Sample Browser page (example: https://cloud.google.com/secret-manager/docs/samples/secretmanager-access-secret-version).

Impact

Having proper guidance will ensure that the samples continue to appear rendering correctly with valuable resources being added.

Challenge

As this involves the team beyond Samples committee, we might have to reach out to the team governing Sample Browser. Luckily, I'm in that team, so I can bring forward any suggestions from this work to the appropriate personnel and/or make the improvements myself on Sample Browser.

[grayside]

I appreciate the value and challenge being raised here, we need a more specific proposal to evaluate.

[grayside]

• We do support links
• Prefer single line links
• Consider using a link shortener, specify the link shortener

[lesv]

I'm inclined to recommend we go with a link shortener to clean up these long URI's.

The recommendations for goo.gl and g.co is to consider using Firebase Dynamic Links. Though goo.gl also mentioned bit.ly & ow.ly.

Firebase Dynamic Links support custom short links as well as a provided one like xyzzy.page.link. Links would then be https://xyzzy.page.link/xxxx - much shorter than current and it's easily updatable, can provide metrics, as well as readability.

My proposal is that we create a cloud devrel firebase project that anyone on the team can join, possibly using Twosync and create a well known prefix that we can use for samples. (Possibly a unique one for each community)

With firebase Dynamic Links we can also use our own domain.

[lesv]

Note it is possible to use g.co, but the process is manual and probably wouldn't easily scale to the level we work at.

[alixhami]

My proposal would be to not allow links within sample content. They're difficult to validate over time and can easily become broken links. I've also seen some awkwardness where a sample includes a link to the documentation page where I'm currently viewing it. If a sample needs a link, I think a more appropriate place for it would be (1) in the language-specific sample preface above the sample content in the docs, (2) in the body of the doc if it applies to all samples, or (3) outside of the region tag area on GitHub if it's something that is useful for GitHub.

If the committee determines that links should be allowed in samples, I think some tooling will be required to make sure links in samples are not broken and that samples in doc pages do not accidentally point to themselves. The guide could also warn about the potential downsides of including links in samples and say to use them only when absolutely necessary.

[lesv]

@alixhami - many of our competitors put more information in samples, not less. On the whole, I'd rather we error on the side of too much. I've heard that from PM's as well in the past.

We have link checkers that we can target sample code, so that shouldn't be an issue, though as soon as we add in short links it will complicate the link checker.

There is a fundamental tension, between those, like me, who feel that samples should stand alone, and those who feel that they should only be viewed within the context of docs. Since they can be discovered independently of our docs, I lean towards good README's and comments in our samples. I'm inclined that we should always have links back to the documentation pages where a sample is discussed.

I'm willing to accept links as being outside of the region tags, so they don't show up in docs. I would also expect any narrative that's replicated in the docs to be there as well.

That said, our auto generated samples are likely to continue to be sparse.