Documentation

[colinbull]

Documentation needs creating /improving.

The documentation needs to really exist at two levels.

1. The general provider needs documenting. this is things like

• Resolution Paths
• Individuals
• Custom query operators like IN (|=|) and Nullable ones

2. Document the specific providers. There are some gotachs around referencing dll's and features that are available, with regards to Stored procedures and Functions

[pezipink]

I will add to 1) here.

People get confused because they reference the official SQL provider's documentation and then wonder why a bunch of the LINQ comp. expression keywords do not work, or work in slightly different ways. We should be clear somewhere that the two providers are not the same, and document with examples the query keywords that are usable and how / where to use them.

CRUD operations and the data context tracking mechanics / controls are not documented at all except on my blog

We don't mention anywhere that this is an erasing type provider (or should I say, a clear distinction is not drawn that we are not generating code)

Another thing we do not make clear is that you must use query { } expressions. It doesn't say you should anywhere, and I have seen several people using Seq. functions (because IQueryable is a sequence) which of course means the TP cannot generate sensible queries, it just selects everything and does stuff client side .

[jwood803]

Looks like using stored procs could use some love, as well?

[pezipink]

Yep sprocs are not documented at all either!

Presently all we really have is my blog, and then in docs/ it is basically the mini-intro page, the "core documentation" which is just a short tutorial on some of the main functionality, and Colin's 3 liner on Oracle.

I think we really need to have a clear notion of "tutorials / howtos / common usage" and "reference".

Up for suggestions of any kind! :)

[colinbull]

Definately, I'm to blame for this did the work but missed the docs. :) only half a job really.

-----Original Message-----
From: "Jon" notifications@github.com
Sent: ‎29/‎01/‎2015 16:09
To: "fsprojects/SQLProvider" SQLProvider@noreply.github.com
Cc: "Colin" colinbul@googlemail.com
Subject: Re: [SQLProvider] Documentation (#112)

Looks like using stored procs could use some love, as well?
—
Reply to this email directly or view it on GitHub.=

[pezipink]

hahaha the core is mostly mine though and I didn't do much either!

Also note we have Sprocs, Functions and other strange Oracle things these days.

It would be great to tie up some loose ends, gets docs sorted than actually release a V1 !

[jwood803]

Well, if there's one place I can definitely help out on it's documentation. :]

I was thinking of doing something similar to how FAKE has their documentation. Thoughts?

[pezipink]

Yes that would be ace. We already have the scaffolding in http://fsprojects.github.io/SQLProvider/index.html this is generated from the stuff in /docs/ and pushed to gh-pages (in case you did not see this)

[jwood803]

That's how I noticed that stored procs weren't there. :]

Just to be sure, this is all in the gh-pages branch, correct? Feel like I'm still not up to speed with all of that.

[pezipink]

Longer term it would be good to have a section on how to extend the sql provider to support your not-currently-supported ADO.NET source, but let's not worry about that yet :)

[pezipink]

the code gets auto-generated and pushed to gh-pages from here
https://github.com/fsprojects/SQLProvider/tree/master/docs

[jwood803]

Ahhh, I see. Thanks for the explanation! I should be able to spend some time throughout the weekend to mess with it.

[pezipink]

Great! Let us know if you need help of any kind. Skype is pezi_pink_42 if you are into that.

Thanks for having a look :)

[jwood803]

Anytime! Glad I can be able to help!

[Thorium]

Question about best practices: If you have e.g. OWIN web-server... What is actually creating and holding the connection / transactions? Can I have one static let ctx = MyProvider.GetDataContext() and use the same ctx everywhere, or should I call this again in every http-post?