diff --git a/api/gpg.go b/api/gpg.go
index 105546609d..578ed18f41 100644
--- a/api/gpg.go
+++ b/api/gpg.go
@@ -19,9 +19,11 @@ type gpgAddKeyParams struct {
 	Keyring     string
 }
 
-// @Summary Add GPG Key
-// @Description Adds a GPG key to aptly keyring
-// @Tags GPG
+// @Summary Add GPG Keys
+// @Description **Adds GPG keys to aptly keyring**
+// @Description
+// @Description Add GPG public keys for veryfing remote repositories for mirroring.
+// @Tags Mirrors
 // @Produce json
 // @Success 200 {object} string "OK"
 // @Failure 400 {object} Error "Bad Request"
diff --git a/api/graph.go b/api/graph.go
index c23b5f02e9..efeb8384c8 100644
--- a/api/graph.go
+++ b/api/graph.go
@@ -13,17 +13,26 @@ import (
 )
 
 // @Summary Graph Output
-// @Description **Generate graph of aptly objects (same as in aptly graph command).**
-// @Description e.g open url `http://localhost:8080/api/graph.svg?layout=vertical` in browser
-// @Tags Graph
+// @Description **Generate dependency graph**
+// @Description
+// @Description Command graph generates graph of dependencies:
+// @Description
+// @Description * between snapshots and mirrors (what mirror was used to create each snapshot)
+// @Description * between snapshots and local repos (what local repo was used to create snapshot)
+// @Description * between snapshots (pulling, merging, etc.)
+// @Description * between snapshots, local repos and published repositories (how snapshots were published).
+// @Description
+// @Description Graph is rendered to PNG file using graphviz package.
+// @Description
+// @Description Example URL: `http://localhost:8080/api/graph.svg?layout=vertical`
+// @Tags Status
 // @Produce json
 // @Param ext path string true "ext specifies desired file extension, e.g. .png, .svg."
 // @Param layout query string false "Change between a `horizontal` (default) and a `vertical` graph layout."
 // @Success 200 {object} []byte "Output"
 // @Failure 404 {object} Error "Not Found"
 // @Failure 500 {object} Error "Internal Server Error"
-// @Router /api/graph [get]
-// GET /api/graph.:ext?layout=[vertical|horizontal(default)]
+// @Router /api/graph.{ext} [get]
 func apiGraph(c *gin.Context) {
 	var (
 		err    error
diff --git a/api/mirror.go b/api/mirror.go
index 0052f2a59c..952c67d365 100644
--- a/api/mirror.go
+++ b/api/mirror.go
@@ -31,7 +31,7 @@ func getVerifier(keyRings []string) (pgp.Verifier, error) {
 	return verifier, nil
 }
 
-// @Summary Get mirrors
+// @Summary Get Mirrors
 // @Description **Show list of currently available mirrors**
 // @Description Each mirror is returned as in “show” API.
 // @Tags Mirrors
@@ -82,8 +82,8 @@ type mirrorCreateParams struct {
 	IgnoreSignatures bool `                  json:"IgnoreSignatures"`
 }
 
-// @Summary Create mirror
-// @Description **Create a mirror**
+// @Summary Create Mirror
+// @Description **Create a mirror of a remote repositoru**
 // @Tags Mirrors
 // @Consume json
 // @Param request body mirrorCreateParams true "Parameters"
diff --git a/api/s3.go b/api/s3.go
index 19be7537a2..f38b084706 100644
--- a/api/s3.go
+++ b/api/s3.go
@@ -6,8 +6,10 @@ import (
 
 // @Summary S3 buckets
 // @Description **Get list of S3 buckets**
-// @Tags S3
-// @Produce  json
+// @Description
+// @Description List configured S3 buckets.
+// @Tags Status
+// @Produce json
 // @Success 200 {array} string "List of S3 buckets"
 // @Router /api/s3 [get]
 func apiS3List(c *gin.Context) {
diff --git a/api/storage.go b/api/storage.go
index 4d306b0b45..c4f478b81c 100644
--- a/api/storage.go
+++ b/api/storage.go
@@ -18,6 +18,8 @@ type diskFree struct {
 
 // @Summary Get Storage Utilization
 // @Description **Get disk free information of aptly storage**
+// @Description
+// @Description Units in MiB.
 // @Tags Status
 // @Produce json
 // @Success 200 {object} diskFree "Storage information"
diff --git a/docs/Database.md b/docs/Database.md
index 804cde5e6d..60e55ef0d0 100644
--- a/docs/Database.md
+++ b/docs/Database.md
@@ -1,4 +1,4 @@
-# Aptly Database Operations
+# Maintenance Operations
 <div>
 Manage aptly’s internal metadata database and package pool.
 </div>
diff --git a/docs/Files.md b/docs/Files.md
index e2b9c83226..84ed30a3ef 100644
--- a/docs/Files.md
+++ b/docs/Files.md
@@ -1,4 +1,4 @@
-# File Operations
+# Upload Package Files
 <div>
 Upload package files temporarily to aptly service. These files
 could be added to local repositories using [local repositories API](/doc/api/repos).
diff --git a/docs/GPG.md b/docs/GPG.md
deleted file mode 100644
index c33bf937db..0000000000
--- a/docs/GPG.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# GPG Keys
-<div>
-
-</div>
diff --git a/docs/Graph.md b/docs/Graph.md
deleted file mode 100644
index 56a31b2fad..0000000000
--- a/docs/Graph.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Dependency Graph
-<div>
-aptly generates graph showing dependencies between mirrors, local repositories,
-snapshots and published repositories.
- 
-
-Command graph generates graph of dependencies:
-
-* between snapshots and mirrors (what mirror was used to create each snapshot)
-* between snapshots and local repos (what local repo was used to create snapshot)
-* between snapshots (pulling, merging, etc.)
-* between snapshots, local repos and published repositories (how snapshots were published).
-
-Graph is rendered to PNG file using graphviz package.
-
-Usage:
-
-    $ aptly graph
-
-Flags:
-
--   `-format="png"`: graph output format, could be anything graphviz supports, e.g. `png`, `pdf`, `svg`, ...
--   `-output=""`: specify output filename, default is to open result in viewer
--   `-layout="horizontal"`: change between a `horizontal` and a `vertical` graph layout.
-
-Example:
-
-<a href="../../../img/graphfull.png"><img src="../../../img/graph.png" alt="Example graph from aptly graph (horizontal)" class="img-responsive"></a>
-
-</div>
diff --git a/docs/Mirrors.md b/docs/Mirrors.md
index a86e6cca29..69aef80ad6 100644
--- a/docs/Mirrors.md
+++ b/docs/Mirrors.md
@@ -1,7 +1,8 @@
-# Repository Mirrors
+# Remote Repository Mirrors
 <div>
-aptly allows to create mirrors of remote Debian repositories, HTTP, HTTPS and FTP repositories are supported.
+Manage mirrors of remote Debian repositories.
+
+HTTP, HTTPS and FTP repositories are supported.
 
-Mirrors are created with [`aptly mirror create`](/doc/aptly/mirror/create/) command, mirror contents are downloaded with [`aptly mirror update`](/doc/aptly/mirror/update/) command. Mirror could be updated at any moment. In order to preserve current mirror state, [create snapshot](/doc/aptly/snapshot/create/) of the mirror. Snapshot could be published or used to build other snapshots.
 </div>
 
diff --git a/docs/Packages.md b/docs/Packages.md
index 77bc5de4c1..8c3731d484 100644
--- a/docs/Packages.md
+++ b/docs/Packages.md
@@ -1,4 +1,4 @@
-# Packages
+# Search Packages
 <div>
 Perform operations on the whole collection of packages in apty database.
 </div>
diff --git a/docs/Publish.md b/docs/Publish.md
index 44d5fdb1ce..2d1f2af0b4 100644
--- a/docs/Publish.md
+++ b/docs/Publish.md
@@ -1,4 +1,4 @@
-# Aptly Publish Points
+# Publish repositories and mirrors
 <div>
 
 Publish snapshot or local repo as Debian repository which could be served by HTTP/FTP/rsync server. Repository is signed by user's key with GnuPG. Key should be created beforehand (see section GPG Keys below).  Published repository could be consumed directly by apt.
diff --git a/docs/Repos.md b/docs/Repos.md
index 8e07ae54bc..aeffda2417 100644
--- a/docs/Repos.md
+++ b/docs/Repos.md
@@ -1,4 +1,4 @@
-# Repositories
+# Manage Local Repositories
 <div>
 Local repository is a collection of packages (most usually custom packages created internally).
 Packages could be added to local repository at any moment, removed, moved or copied between repos.
diff --git a/docs/S3.md b/docs/S3.md
deleted file mode 100644
index d5c310884f..0000000000
--- a/docs/S3.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# S3 Endpoints
-<div>
-
-</div>
-
diff --git a/docs/Snapshots.md b/docs/Snapshots.md
index 42259a62c6..882c64c0a4 100644
--- a/docs/Snapshots.md
+++ b/docs/Snapshots.md
@@ -1,4 +1,4 @@
-# Repository and Mirror Snapshots
+# Manage repository and mirror Snapshots
 <div>
 Snapshot is a fixed state of remote repository mirror or local repository. Internally snapshot is list of references to packages. Snapshot is immutable, i.e. it can’t be changed since it has been created. Snapshots could be merged, filtered, individual packages could be pulled, snapshot could be verified for missing dependencies. Finally, snapshots could be published as repositories.
 </div>
diff --git a/docs/Status.md b/docs/Status.md
index e19de2dbcd..5ccf8e149b 100644
--- a/docs/Status.md
+++ b/docs/Status.md
@@ -1,10 +1,5 @@
 # Aptly Status Information
 <div>
-
-## Something
-
-Very interesting ... asd wer
-
-
+Various status information.
 
 </div>
diff --git a/docs/docs.html b/docs/docs.html
index 35eb3c9b0d..e0f4eda0ab 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -39,6 +39,11 @@
         font-size: 16pt !important;
     }
 
+    /* Group Spacing */
+    .swagger-ui .opblock-tag-section {
+        padding-top: 40px !important;
+    }
+
     /* Tag Group */
     .swagger-ui .opblock-tag-section > .opblock-tag > a {
         color: grey !important;
@@ -51,7 +56,6 @@
     .swagger-ui .opblock-tag-section .opblock-tag .markdown > h1 {
         font-size: 14pt;
         margin-top: 0px;
-        margin-left: 1em;
     }
 
     /* Group Description */
diff --git a/docs/swagger.conf.tpl b/docs/swagger.conf.tpl
index e846c5701a..31b0dfbff0 100644
--- a/docs/swagger.conf.tpl
+++ b/docs/swagger.conf.tpl
@@ -10,24 +10,18 @@ package docs
 // @Tag.description.markdown
 // @Tag.name Files
 // @Tag.description.markdown
-// @Tag.name Packages
-// @Tag.description.markdown
 // @Tag.name Mirrors
 // @Tag.description.markdown
 // @Tag.name Snapshots
 // @Tag.description.markdown
 // @Tag.name Publish
 // @Tag.description.markdown
-// @Tag.name Graph
-// @Tag.description.markdown
-// @Tag.name S3
+// @Tag.name Packages
 // @Tag.description.markdown
-// @Tag.name GPG
+// @Tag.name Status
 // @Tag.description.markdown
 // @Tag.name Database
 // @Tag.description.markdown
-// @Tag.name Status
-// @Tag.description.markdown
 // @Tag.name Tasks
 // @Tag.description.markdown