Docs: Need: Instructions on how to download samples

[Rick-Anderson]

The problem: We tell customers to download the sample. We provide a link to the sample, but you can't download from the sample link. You need to figure out:

Navigate to repro.
Download the entire repro (and probably unzip)
navigate to the sample
ACOM had re-usable sections - How did ACOM migrate without shared/included sections. That's what we need here. Should we request this feature? Until it comes, we need one document explaining the process. That doc should probably live in the .NET repo.

Original issue: https://github.com/aspnet/Docs/issues/565

cc @dend

[mairaw]

Do we have a feature request tracking this internally? Otherwise, it's not on their radar.

/cc @dend @Rick-Anderson

[Rick-Anderson]

Do we have a feature request tracking this internally?

No. Should I create one?

[mairaw]

@dend @EisenbergEffect can you guys comment if this is something that you already have in the backlog in terms of feature requests for docs?

[EisenbergEffect]

@dend is the best person to address that.

[mairaw]

@Rick-Anderson for the article itself, did you think about having an actual topic on docs or just an article in our styleguide section on GH for example?

[guardrex]

We've decided to add a short instruction section ("get the repo to get the sample") to the bottom of Samples and Tutorials. Where samples are mentioned across the repo, I'll add a link to this section. When the process changes later (e.g., they can download a zipped sample or something), we'll just update the instruction.

[Rick-Anderson]

I think It should be an include that every article that has code can include. cc @tdykstra

[guardrex]

Add the entire instruction as an include ... or just the link to the instruction?

[guardrex]

If I can craft a tight instruction, we could just add (via include) to each spot. I'll float language here first if that's what you were thinking.

[Rick-Anderson]

I think an include is better so you're not sending them off to another article.

[guardrex]

ok ... let me see if I can word something short and sweet for it here.

[Rick-Anderson]

@mairaw @tdykstra how would you like to do download instructions?
@GuardRex - @mairaw @tdykstra might have different (better) ideas.

[guardrex]

@mairaw and I discussed it offline, which is why I was proceeding.

[mairaw]

adding @BillWagner to the discussion too. I think that a link might be better. I don't think I want to add the entire instruction every time I link to a sample.

[Rick-Anderson]

@mairaw You're right, many times we don't want full blown instructions. Maybe link for now and we can think about include later on.

[guardrex]

1. The [source|sample] for this topic is available on GitHub (Download instructions).
2. The [source|sample] for this topic is available on GitHub (Instructions).
3. The [source|sample] for this topic is available on GitHub. For information on downloading the [source|sample], see Samples and Tutorials.

Samples and Tutorials link is directly to the section of that doc.

[guardrex]

Which one tho? ... I was going to go thru and update all of our sample mentions.

[tdykstra]

How about

See the sample app for this topic. For information about how to download it, see Samples and Tutorials.

Accessibility rule for link text is it should describe what you're getting -- "GitHub" is suboptimal

"sample app" would have to change where all we have are isolated code files.

[guardrex]

See

They'll see it in the topic, and I'm a little concerned that many will take that as a clear instruction to "see it" before seeing it in the topic. My suggestion is to clearly identify this link for downloading the sample.

I agree on the link text. The sentence (or that format) I show :point_up: is common in the docs.

about

I prefer "on" ... IIRC "about" means "generally pertaining," while "on" means "directly pertaining." However, I can make a shorter version without either word. :point_down:

Try this one ...

Download the sample for this topic. For download instructions, see Samples and Tutorials.

That way if they pretty much know they don't want to get the sample, they'll know to just skip that.

[tdykstra]

Looks good. Let's be sure to tell them in the instructions in Samples and Tutorials that if they just want to look at the code they don't have to download.