Solve some low hanging fruit in the documentation (#4279)

Ultimately I was trying this out to see whether we can tweak the docs
easily, it made me realize that our docs are tailored to general GraphQL
rather than how do we use this library. It made me come up with a few
suggestions

- We should have a toggle on code examples to switch between
`buildSchema` and programatically creating the schema with i.e.
`GraphQLObjectType`
- Our documentation starts with a tutorial, this ultimately feels like a
mistake, we should lead with an explanation of what GraphQL.JS is and
what it aims to do, clearly outlining the goals of this project
- We should line out use-cases for building on this library and best
practices of how to go to production

Resolves #2941 
Resolves #2567

Author: JoviDeCroock

website/pages/execution.mdx

@@ -40,10 +40,14 @@ export function execute(
 
 type MaybePromise<T> = Promise<T> | T;
 
-type ExecutionResult = {
-  data: Object;
-  errors?: GraphQLError[];
-};
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  data?: TData | null;
+  extensions?: TExtensions;
+}
 ```
 
 Implements the "Evaluating requests" section of the GraphQL specification.
@@ -56,3 +60,25 @@ a GraphQLError will be thrown immediately explaining the invalid input.
 `ExecutionResult` represents the result of execution. `data` is the result of
 executing the query, `errors` is null if no errors occurred, and is a
 non-empty array if an error occurred.
+
+### executeSync
+
+```ts
+export function executeSync(
+  schema: GraphQLSchema,
+  documentAST: Document,
+  rootValue?: mixed,
+  contextValue?: mixed,
+  variableValues?: { [key: string]: mixed },
+  operationName?: string,
+): ExecutionResult;
+
+type ExecutionResult = {
+  data: Object;
+  errors?: GraphQLError[];
+};
+```
+
+This is a short-hand method that will call `execute` and when the response can
+be returned synchronously it will be returned, when a `Promise` is returned this
+method will throw an error.

website/pages/graphql.mdx

@@ -144,6 +144,15 @@ function graphql(
   variableValues?: { [key: string]: any },
   operationName?: string,
 ): Promise<GraphQLResult>;
+
+interface ExecutionResult<
+  TData = ObjMap<unknown>,
+  TExtensions = ObjMap<unknown>,
+> {
+  errors?: ReadonlyArray<GraphQLError>;
+  data?: TData | null;
+  extensions?: TExtensions;
+}
 ```
 
 The `graphql` function lexes, parses, validates and executes a GraphQL request.

website/pages/type.mdx

@@ -188,16 +188,20 @@ const MyAppSchema = new GraphQLSchema({
 ### GraphQLScalarType
 
 ```ts
-class GraphQLScalarType<InternalType> {
-  constructor(config: GraphQLScalarTypeConfig<InternalType>);
+class GraphQLScalarType<InternalType, ExternalType> {
+  constructor(config: GraphQLScalarTypeConfig<InternalType, ExternalType>);
 }
 
-type GraphQLScalarTypeConfig<InternalType> = {
+type GraphQLScalarTypeConfig<InternalType, ExternalType> = {
   name: string;
   description?: string;
-  serialize: (value: mixed) => InternalType;
-  parseValue?: (value: mixed) => InternalType;
-  parseLiteral?: (valueAST: Value) => InternalType;
+  specifiedByURL?: Maybe<string>;
+  serialize: (outputValue: unknown) => ExternalType;
+  parseValue?: (inputValue: unknown) => InternalType;
+  parseLiteral?: (
+    valueAST: Value,
+    variables?: Maybe<Record<string, unknown>>,
+  ) => InternalType;
 };
 ```
 
@@ -210,19 +214,30 @@ functions used to ensure validity.
 ```js
 const OddType = new GraphQLScalarType({
   name: 'Odd',
-  serialize: oddValue,
-  parseValue: oddValue,
+  // Can be used to link to a specification
+  // for this scalar, for instance the JSON
+  // specification.
+  specifiedByURL: '',
+  description:
+    'This custom scalar will only return a value if the passed in value is an odd integer, when it's not it will return null.'
+  serialize: (outputValue) => {
+    // This function gets called for response-data, the application returns data
+    // for a property and in the schema we see that this value has the "Odd" type.
+   return typeof outputValue === 'number' && outputValue % 2 === 1 ? value : null;
+  },
+  parseValue: (inputValue) => {
+    // This function gets called for input-data, i.e. variables being passed in
+    return typeof inputValue === 'number' && outputValue % 2 === 1 ? value : null;
+  },
   parseLiteral(ast) {
+    // This function gets called when the value is passed in as a literal on the
+    // Executable GraphQL Document
     if (ast.kind === Kind.INT) {
       return oddValue(parseInt(ast.value, 10));
     }
     return null;
   },
 });
-
-function oddValue(value) {
-  return value % 2 === 1 ? value : null;
-}
 ```
 
 ### GraphQLObjectType