Merge branch 'cablett-graphql-pagination' into 'master'

Add docs for shortcut fields

See merge request gitlab-org/gitlab!27859

doc/development/api_graphql_styleguide.md

@@ -211,6 +211,15 @@ To ensure that we get consistent ordering, we will append an ordering on the pri
 key, in descending order. This is usually `id`, so basically we will add `order(id: :desc)`
 to the end of the relation. A primary key _must_ be available on the underlying table.
 
+#### Shortcut fields
+
+Sometimes it can seem easy to implement a "shortcut field", having the resolver return the first of a collection if no parameters are passed.
+These "shortcut fields" are discouraged because they create maintenance overhead.
+They need to be kept in sync with their canonical field, and deprecated or modified if their canonical field changes.
+Use the functionality the framework provides unless there is a compelling reason to do otherwise.
+
+For example, instead of `latest_pipeline`, use `pipelines(last: 1)`.
+
 ### Exposing permissions for a type
 
 To expose permissions the current user has on a resource, you can call