refactor(doc): improve documentation based on MR feedback

doc/api/api_resources.md

@@ -105,7 +105,7 @@ The following API resources are available outside of project and group contexts
 
 | Resource                                          | Available endpoints                                                     |
 |:--------------------------------------------------|:------------------------------------------------------------------------|
-| [Appearance](appearance.md)                       | `/application/appearance`                                               |
+| [Appearance](appearance.md) **(CORE ONLY)**       | `/application/appearance`                                               |
 | [Applications](applications.md)                   | `/applications`                                                         |
 | [Audit Events](audit_events.md) **(PREMIUM ONLY)** | `/audit_events`                                                         |
 | [Avatar](avatar.md)                               | `/avatar`                                                               |

doc/api/appearance.md

-# Appearance API
+# Appearance API **(CORE ONLY)**
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/20674) in GitLab 12.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16647) in GitLab 12.7.
 
-These API calls allow you to read and modify the GitLab appearance as visible in
-`/admin/appearance`. You have to be an administrator in order to perform this action.
+Appearance API allows you to maintain GitLab's appearance as if using the GitLab UI at
+`/admin/appearance`. The API requires administrator privileges.
 
 ## Get current appearance configuration
 
@@ -47,10 +47,10 @@ PUT /application/appearance
 | --------------------------------- | ------- | -------- | ----------- |
 | `title`                           | string  | no       | Instance title on the sign in / sign up page
 | `description`                     | string  | no       | Markdown text shown on the sign in / sign up page
-| `logo`                            | mixed   | no       | Instance image user on the sign in / sign up page
+| `logo`                            | mixed   | no       | Instance image used on the sign in / sign up page
 | `header_logo`                     | mixed   | no       | Instance image used for the main navigation bar
 | `favicon`                         | mixed   | no       | Instance favicon in .ico/.png format
-| `new_project_guidelines`          | string  | no       | Markmarkdown text shown on the new project page
+| `new_project_guidelines`          | string  | no       | Markdown text shown on the new project page
 | `header_message`                  | string  | no       | Message within the system header bar
 | `footer_message`                  | string  | no       | Message within the system footer bar
 | `message_background_color`        | string  | no       | Background color for the system header / footer bar

lib/api/appearance.rb

@@ -22,9 +22,9 @@ module API
     end
     params do
       optional :title, type: String, desc: 'Instance title on the sign in / sign up page'
-      optional :description, type: String, desc: 'Markmarkdown text shown on the sign in / sign up page'
+      optional :description, type: String, desc: 'Markdown text shown on the sign in / sign up page'
       # TODO: remove rubocop disable - https://gitlab.com/gitlab-org/gitlab/issues/14960
-      optional :logo, type: File, desc: 'Instance image user on the sign in / sign up page' # rubocop:disable Scalability/FileUploads
+      optional :logo, type: File, desc: 'Instance image used on the sign in / sign up page' # rubocop:disable Scalability/FileUploads
       optional :header_logo, type: File, desc: 'Instance image used for the main navigation bar' # rubocop:disable Scalability/FileUploads
       optional :favicon, type: File, desc: 'Instance favicon in .ico/.png format' # rubocop:disable Scalability/FileUploads
       optional :new_project_guidelines, type: String, desc: 'Markmarkdown text shown on the new project page'