search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.64k stars 25.29k forks source link

Put the name of the file directly above code samples #20499

Closed gregoryagu closed 4 years ago

gregoryagu commented 4 years ago

I just want to mention that I really like it when the name of the file that should be created is directly above the code sample, like this:

Blazor uses natural HTML tags for UI composition. The following Razor markup demonstrates a component (Dialog.razor) that displays a dialog and processes an event when the user selects a button:

Dialog.razor

<div class="card" style="width:22rem">
    <div class="card-body">
        <h3 class="card-title">@Title</h3>
        <p class="card-text">@ChildContent</p>
        <button @onclick="OnYes">Yes!</button>
    </div>
</div>
...

Even though it is mentioned in the line of text above it, it makes it much more clear to have it directly above. For example, this is the way that I usually read the docs:

  1. First Pass - read all of it, including the code sample.
  2. Second Pass, I create a sample project, and then cody and paste the code into my own app, creating the components. When the name is directly above, it is crystal clear what I need to name it. When it is embedded in the text, I usually miss that, and name it whatever comes to mind. Then later, I will find that the name was actually specified.

For example, this doc in the Bind Across more than two components uses the method of putting the file name directly above the code, and that is much appreciated.

If the name doesn't matter, then of course this is not needed.

I can't find it just now, but there have been instances of my being confused about this before in the docs, so wanted to bring it to your attention.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

guardrex commented 4 years ago

I agree, and you'll find that there are many that are just like that all through the docs. However, not all of them have it. For one thing, several of the topics were written by other authors, and they didn't do it. Also, we work on these docs continuously (and quickly 🏃) dropping in new examples all the time ... some of them miss getting the file name above them.

As I make the UE (user experience) passes on all of the topics over the holidays, I'll try to add them to any code examples where they don't appear. I'll update this example and move the file name (Dialog.razor) to that position.

Thanks for the feedback. I will take care of this over the ⛄ holidays 🎁.

gregoryagu commented 4 years ago

Sounds great Luke. As a note, I saw this example of putting the file name on the right on this site and I thought I would pass it on:

image

guardrex commented 4 years ago

We don't have that capability, and we only work on content here. You could suggest that to the docs engineers tho ... open an issue and explain/show it to them at ...

https://github.com/MicrosoftDocs/feedback/issues

guardrex commented 4 years ago

Hummmm 🤔 ...

[!code-cshtml[HelloWorld.razor](../../../samples/components/HelloWorld.razor)]

... so they're using the comment field. I didn't think we rendered anything from that.

I'll do a quick test right now and see what happens and report back in a bit.

guardrex commented 4 years ago 
[!code-csharp[TodoItem.cs](build-a-blazor-app/samples_snapshot/TodoItem.cs)]

No ❤️ @gregoryagu ...

Capture

I'll leave it up to you if you want to float that suggestion to them on their repo at :point_right: https://github.com/MicrosoftDocs/feedback/issues.

UPDATE: Test was reverted on https://github.com/dotnet/AspNetCore.Docs/pull/20546.

gregoryagu commented 4 years ago

Opened #3266