EF FAQ Relocation and Overhaul

  • Article

It has been quite some time since I last updated the EF Frequently Asked Questions which makes them dramatically less useful to everyone.  At its core, I think the reason for this delay is not just that I have been busy doing other things but rather that the way the FAQ was setup and posted made it difficult for others to help keep it up to date.  To have any hope of continuing to be a great and useful resource in the long run, I believe this needs to be a community effort rather than one run by a single individual or by the EF team.

In an attempt to improve matters, I’ve spent some time over the last few weeks relocating the FAQ to <www.ef-faq.org> (a domain that I registered personally, not something officially owned or maintained by Microsoft) and changing its source format into a series of text files with simple wiki-like markup maintained under mercurial-based source control at the codeplex project <effaq.codeplex.com/>.  In addition, some folks on the EF team have put a lot of effort into adding additional questions and answers and updating things based on EF4 so hopefully the FAQ is in a better place than it has been for a while.

Now my hope is that some of you will take a few minutes to help me out in the following ways:

  1. Look over the FAQ—maybe you will learn something.
  2. Next time you have a question or answer a question, check the FAQ, and if the answer is already there publish a link so that others can more easily find and benefit from it.  Every question has a fragment name based on the section and question #.  So if you want a link, for instance to Code Generation Question 12.2 (“Is there any way to use public, easily modifiable templates for EF code generation?”), the link would be <www.ef-faq.org/code-generation.html#12.2>
  3. If the question you have is NOT answered in the FAQ, and you think it is something others may also run into.  Please, PLEASE, take the time to enlist in the codeplex project, edit the source, make a fork and send a pull request so that we can incorporate your change and push it up to the site.  This is designed to be a pretty easy process, and it can really benefit your fellow programmers.

For the curious, here’s a little background about how the new EF FAQ site is put together: After casting about for a bit, I decided that I wanted to have a static site with pretty simple HTML so that it is simple, quick and search-engine friendly.  I wanted more formatting than I could get from strict plain text, but I wanted something simpler and more constrained/uniform than what I could get out of word or something like that.  In the end I decided to take the markdownsharp library (thanks Jeff and others), extend it a little bit to add the concept of “sections” and “questions” which get auto-numbered, have some specific HTML markup and help to produce an auto-generated index of sections for navigation.  I also wrote a simple program to wrap the generated content HTML in a high-level template so that every page gets a header, footer and navigation bar and to manage the workflow of turning the various source files into all the HTML for the site.  You can find the source for my “faqbldr” app as part of the codeproject as well, and soon I hope to push my extensibility hooks for markdownsharp back into its repository so that I can remove its source from the codeplex project and just check in a binary nuget-style.

By the way, if you are an HTML and CSS guru with a strong stomach, you might want to take a look at template.html in the codeplex project where I have created a horrendous mess that no doubt violates every rule of good HTML design but somehow seems to have landed in a place where the site works and looks OK as long as I don’t touch it any more (If I do I’m pretty sure the whole house of cards will come tumbling down).  Someone who wasn’t such an awful html hacker like me could no doubt make it cleaaner, nicer looking and faster.

One last comment, while the FAQ has originally been produced by members of the EF team (and likely some EF team members will continue to contribute to it), it is definitely my intention that this not just be a Microsoft effort.  This isn’t official documentation.  Ideally it should be a helpful resource that contains whatever info you need to help get your tasks programming with the EF done (or more frequently pointers to where to find the more complete details on what you need).  This means that if you have negative comments about the EF in some area or positive comments about some other product that you would use in conjunction with the EF or instead of it in some scenario, those belong here as well—as long as they are constructive and help achieve the goal of making people successful at building great software.  Happily Craig Stuntz has agreed to start contributing to the project, and it’s my hope that we’ll have others join in soon.

- Danny

P.S. If you visit the site in the next day or two, you will find that the bing search box in the upper left isn’t fully working yet because the site is so new and bing hasn’t indexed it, but that should fix itself in the next few days.