New doc on context pooling

[Rick-Anderson]

Fixes #501, Fixes #1181

Internal review URL

[Rick-Anderson]

@daniel-white @ROMYIM @Menighin please review

[roji]

Thanks @Rick-Anderson, good to see all these great docs!

[roji]

As a general rule, we try to always put code samples under the samples in this repo, and reference it - this makes sure code always works and is up to date (we build the sample repo as part of the docs CI).

[Rick-Anderson]

@roji do you want me to add a project to samples that just has a main that calls startup with this code

[Rick-Anderson]

@ajcvickers this change allows the repo to use xref tags like I added to the new doc
<xref:Microsoft.EntityFrameworkCore.DbContext>

[roji]

I think the consensus we reached in the team is that we backtick a type once when we introduce it, but remove backticks later to make the text flow better. For DbContext specifically, we generally prefer to talk about "context" - I've submitted suggestions to do so.

Apart from that it all looks good to me.

[Rick-Anderson]

I think the consensus we reached in the team is that we backtick a type once when we introduce it, but remove backticks later to make the text flow better. For DbContext specifically, we generally prefer to talk about "context" - I've submitted suggestions to do so.

Apart from that it all looks good to me.

The MS style guide is very clear on this. The first use should use <xref:type> and subsequent should all be code fenced. That's how all of docs.ms.com is supposed to be written.

Note this PR adds "xref_query_tags": [ to .openpublishing.publish.config.json to make that possible.

[ajcvickers]

@Rick-Anderson The problem is that the rendering is so ugly... We really don't want our docs to be unreadable in this way. Can you point to the data that shows always fencing creates more readable docs? Or some other data-based reason that the docs are this way?

[Rick-Anderson]

I think I may have misunderstood. Changing DbContext to context is fine, as context is not a type. Rarely can you substitute a type for a general term.

The problem is that the rendering is so ugly...

If you're talking about types, my guess is the consensus is fencing makes the doc look better. Perhaps your eyes need to get used to it. It's also a consistency issue with docs.ms.com. I think most writers would say it looks better with types fenced and makes the docs more readable.

On problem with replacing DbContext with context is that context is now localized, and in some languages that can be problematic.

Can you point to the data that shows always fencing creates more readable docs? Or some other data-based reason that the docs are this way?

I'll bring it up with the folks who author the style guide. They usually have sound reasons for each rule AFAIK.

[roji]

I do agree we should be consistent with general MS docs standard, the thing is that this is the way our docs are currently written pretty much across the board. As an example, see DbSet in the docs on entity types. We could obviously change everything (again) if needed, but for now it is what it is (and I think we like it).

Re localization for context, unfortunately I think that's a pretty universal problem. For example, we fence the AddDbContextPool method, but then talk about pooling (the concept) in English - the two may end up completely disconnected after localization, etc.

[Paul-Dempsey]

"context" may be clearer, and translate better if you say: "database context", and on first use, (similar to acronyms), say "database context (DbContext)". Then it is clear that you are introducing specific terminology.