I’m finally ready to start the tutorial, (Getting Started), which is a top link in Bing/Google searches for “Entity Framework Tutorial”. I haven’t blogged for a while: someone found bugs in an automation tool that I wrote, so I got to be a developer again. This post is a bit longer than I usually do.
The key audience for a “Getting Started” topic is beginners. The goal is to get them past all the nits and pitfalls that prevent them from getting anything at all done.
It’s tricky writing for them: you must give them enough context so they learn something, and understand what is going on; but don’t drown them in unnecessary details. I like to tell them stuff right when they are using it: the “Just in Time” approach.
Is this just my personal opinion, based on how I learn technology? Would someone with a different learning style prefer a different approach? That’s a legitimate question, and it’s hard to get into the head of someone with a different learning style. My main evidence for this approach is the usability studies we did of the WCF Getting Started Tutorial, where we found that it greatly improved people’s ability to complete the tutorial.
The EF Getting Started does not use this approach. The section starts with three conceptual overview topics about Entity Framework, followed by a tutorial which accompanies each step with limited discussion.
Here’s my bottom-line critique of the section. First, since I was able to successfully complete the tutorial, the section succeeds in its main objective. However, although the overview topics are very informative and contain lots of information, IMHO this level of detail is overkill for beginners. These topics should be moved to a separate “EF Overview” section that might follow this section. Also, the tutorial steps need a bit more context added to each of them.
I’ll walk through the section in detail. I’m very interested in your feedback: whether you agree with this critique, and what your experience was in going through the tutorial. New releases of Entity Framework are coming, so we are unlikely to go back and rewrite this tutorial; but your opinions and feedback can affect how we write future tutorials.
The first topic is Generating Models and Mappings, which starts off describing the three XML-based languages underlying EF. This is pretty scary, because the term “language” made me think I’d be coding in it. To be fair, the topic does say that the XML files are generated. But if so, then why are they telling me about them in such detail? Then the topic tells me about a command line tool (EdmGen.exe) which is never referenced in the tutorial, followed by a discussion of keys, which should be integrated with the tutorial steps. Finally we get to “The School Model”, which discusses the tables in the database. This content should go into the first section of the Quickstart topic (Creating the School Sample Database).
The next topic, Mapping a Conceptual Model to a Storage Model, discusses the three XML languages used in EF, and gives samples of each, which implies that the tutorial will be using the XML. This is both scary and untrue (again, too much detail for a beginner).
The final overview topic, Working With Entity Data: also too detailed. It starts off discussing “client views”, which are never referenced in the tutorial, and then shows an EF architecture diagram, which provides more detail than the tutorial uses. Next the topic discusses “Querying Objects” and the ObjectContext class, and what to do about the LazyLoadingEnabled property. It then shows me two code samples from the actual tutorial. Since I have yet to do a single step of the tutorial, I have no context for any of this.
It turns out that the ObjectContext class is the key to connecting the conceptual model in the application to the SQL Server objects in the database. All of the code that actually messes with data uses methods in this class. Unfortunately this wasn’t clear to me when first reading this section, because the discussion of it is buried amidst a flood of other details. These discussions ought to be right next to the code snippets in the Quickstart section.
Finally I get to the Quickstart overview topic, which tells me what I will learn, how the tutorial is structured, and what the requirements are to run it — pretty well organized.
I was able to run the steps just fine, so Getting Start succeeds in its main goal. I hit some minor nits due to windows titles changing after the topics were written, but this is a constant hazard of writing about evolving software. The main thing I would change is to add more context and explanation to each step, rather than have all the content in the three preceding topics.
The first step is Creating the School Sample Database, which includes a huge chunk of inline code to copy, followed by a section that describes how to display the database structure by using the Object Browser.
It would be nice to hide the code, by having it be downloaded from somewhere, since there are readers who will not realize that there is stuff to read after the code. Also, this section uses one tool to display the db structure, while Generating Models and Mappings uses a different tool: for simplicity and consistency, only one tool should be used. I would discuss the db structure a bit, and mention that the Person table includes students (non-null enrollment date) and instructors (non-null hire date). I’d contrast this with the Course table, which contains common data, and which is linked to the OnlineCourse and OnsiteCourse tables. I might also talk about keys here.
The second step, Creating the Course Manager Application, should be retitled “Creating the Course Manager User Interface”, since the data access logic is provided in the next steps.
The third step, Generating the School .edmx File, is at the right level of detail, describing the two models (conceptual and data store) and the mapping between them.
The fourth step, Querying Entities and Associations, connects the UI to the database by providing read access. The fact that the SQL query logic is expressed using LINQ should be called out and discussed. Since the ObjectContext class is used, some discussion of it would fit well, since that appears to be how a call to a C# object manages to retrieve rows from the database.
So what do you think? I’m pretty opinionated about how to write for beginners: how new people learn a technology is very interesting to me, and important for Microsoft to understand. Do these comments resonate with you? Or did you find the tutorial spot on? Let me know!