Feedback from docs verification

[ajcvickers]

@divega I think we should have a brainstorming session with the team (maybe in a design meeting slot) to come up with a plan for updating the docs, but for now I'm attempting to bring all the feedback from the recent verification into one place so we don't lose it. Feel free to move it/split it if you would prefer.

• Make sure BuildWebHost pattern is called out in our walkthroughs as well as MVC ones:
  https://github.com/aspnet/Release/issues/205#issuecomment-316507969
• Command line reference: https://github.com/aspnet/Release/issues/193#issuecomment-316793613
  • Documentation for "Environment" needs to be updated--removed/changed in 2.0
  • Supported frameworks for dotnet ef needs to be updated
  • "runtime" flag needs to be documented and is available in CLI but not in PMC
  • Documentation contains no info other than what is shown in help for each command--can we add more details
• Sample code is not runable as-is. We need to decide whether to change this, create separate samples, or make it explicit that these are just snippets
  • Collection is null because no lazy loading and no Include: Feedback: EF Doc walkthrough: Saving data #423
  • Code does not seed the database, so queries fail due to no data: Feedback: EF Doc walkthrough: Saving data #423
  • Loading related data throws for similar reason: https://github.com/aspnet/Release/issues/190#issuecomment-316526902
  • Code uses a TVF but it is not created: https://github.com/aspnet/Release/issues/190#issuecomment-316776176
• IsReadOnlyAfterSave is obsolete Feedback: EF Doc walkthrough: Saving data #423
• Removing relationships docs and related cascade delete info is frustrating and hard to follow Feedback: EF Doc walkthrough: Saving data #423
• Layout of samples is a bit weird: C:\Github\EntityFramework.Docs\samples\core\Querying\Querying https://github.com/aspnet/Release/issues/190#issuecomment-316191233
• public List<Post> OwnedBlogs { get; set; } is wrong https://github.com/aspnet/Release/issues/190#issuecomment-316460473
• Default model has cascade cycles on SQL Server: https://github.com/aspnet/Release/issues/190#issuecomment-316525166
• FromSQL code is wrong: https://github.com/aspnet/Release/issues/190#issuecomment-316541130
• Model building: https://github.com/aspnet/Release/issues/189
  • The purpose of Shadow Property is badly described.
  • Need to remove references of multiple providers e.g. ForSqlServerColumnType
  • Structure of relationships page is mixed in form of how to configure type of relationship & type of Configuration.
  • There should be page describing configuration sources
  • Generated values examples needs to elaborate more on value generation.
  • ConcurrencyToken page needs to specify how to utilize them actually.
  • Needs details on when to use shadow properties before how to configure one.
  • Neither of inheritance says about HasBaseType API. Inheritance is always setup by convention and fluent API specifies how to configure discriminator only.
  • Use case of backing field is missing.
  • Under relational modeling, PK/Index/AK/FK has only constraint name. Do we need separate pages?

[smitpatel]

Structure of relationships page is mixed in form of how to configure type of relationship & type of Configuration.

Also there is no info that if you have multiple navigation pairs then convention won't discover relationship and you need to configure them explicitly.

[divega]

@smitpatel actually, it is there. See the first warning in https://docs.microsoft.com/ef/core/modeling/relationships. It is not great though, you wouldn't know unless you read the manual. I am more concerned about the behavior than it being documented 😄

[divega]

@ajcvickers I have addressed a good number of items as part of the work for 2.0. We should later discuss a plan for the remaining items.

[ajcvickers]

@divega To create new issues for the remaining items

[divega]

Created new separate issues for remaining work.