search

dotnet / EntityFramework.Docs

Documentation for Entity Framework Core and Entity Framework 6
https://docs.microsoft.com/ef/
Creative Commons Attribution 4.0 International
1.62k stars 1.96k forks source link

Add no-loc: metadata to all topics to prevent over localizing. #3068

Open Rick-Anderson opened 3 years ago

Rick-Anderson commented 3 years ago

In https://github.com/dotnet/AspNetCore.Docs, we use no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]

I'll be adding "EF Core" to that list. Let me know if you'd like me to add no-loc to your docs and what terms you'd like added.

related https://github.com/dotnet/AspNetCore.Docs/issues/21420

roji commented 3 years ago

@Rick-Anderson this would allow disabling localization without fencing everywhere, right? If so, that sounds great to me - we fence terms such as DbContext to avoid localization, though we feel it breaks reading fluidity to have so much fencing (plus we don't do it consistently).

Am not sure what the list should contain, we can start with a few obvious things like DbContext and expand it as appropriate...

Rick-Anderson commented 3 years ago

@Rick-Anderson this would allow disabling localization without fencing everywhere, right? If so, that sounds great to me - we fence terms such as DbContext to avoid localization,

Correct

though we feel it breaks reading fluidity to have so much fencing (plus we don't do it consistently).

I know that's your feeling, but most folks outside of EF feel the opposite. My guess is your eyes are used to non-code fencing and the rest of MS.doc.com is used to them so prefers code fencing. Not fencing types is also inconsistent with the rest of the docs.

Am not sure what the list should contain, we can start with a few obvious things like DbContext and expand it as appropriate...

Ask the rest of the team to come up with a list. I'll add them to each doc. It's really easy to add new terms.

roji commented 3 years ago

OK @Rick-Anderson, thanks for the input - I know we're a bit... idiosyncratic on some things. I'll bring this up in out next design meeting.

Rick-Anderson commented 3 years ago

Given that we know several cases where types are MT (machine translated), the safest thing is to follow the MS style guide.

roji commented 3 years ago

@Rick-Anderson we've discussed this as a team, and we agree to code-fence (or xref). We still think that having so many of these in a paragraph (or even sentence) is jarring and a non-ideal user experience, but hope that this can be taken up as a design issue and improved. I'll submit a PR to fix the specific issues that have been flagged, and we'll do a more systematic pass to code-fence later.

In the meantime, can you please add DbContext specifically to our no-loc list (at least until we do all the fencing)? We'll add other terms to it as needed afterwards.

IEvangelist commented 3 years ago

Hi @roji - I hope all is well. I wanted to chime in quick and echo @Rick-Anderson on this thread. While I do understand the concern you're expressing, it would be just as jarring to have one area of the docs that doesn't follow the style guidelines.

I do not believe that it's jarring to read a paragraph or a even a sentence that styles an object as such. But this is an opinion, I do however think that the inline code style could be improved upon.

roji commented 3 years ago

When discussing with the team, the general sentiment seemed to be that at least with the current design (very prominent gray background), lots of fences in a sentence/paragraph are really problematic. But indeed that could be purely a design issue - which we've been dealing with by not fencing so much. In any case, we're discussed and are OK to fence all code.