diff --git a/api/files.go b/api/files.go
index 6b2ddba5..2d042a5d 100644
--- a/api/files.go
+++ b/api/files.go
@@ -34,8 +34,14 @@ func verifyDir(c *gin.Context) bool {
 	return true
 }
 
-// @Summary List Files
-// @Description **Get list of uploaded files**
+// @Summary List Directories
+// @Description **Get list of upload directories**
+// @Description
+// @Description **Example:**
+// @Description  ```
+// @Description  $ curl http://localhost:8080/api/files
+// @Description  ["aptly-0.9"]
+// @Description  ```
 // @Tags Files
 // @Produce json
 // @Success 200 {array} string "List of files"
@@ -67,9 +73,17 @@ func apiFilesListDirs(c *gin.Context) {
 	c.JSON(200, list)
 }
 
-// @Summary Upload file glaa
-// @Description **Upload a file to a directory**
-// @Description Any number of files can be uploaded in one call; aptly preserves filenames. No check is performed if existing uploaded file would be overwritten.
+// @Summary Upload Files
+// @Description **Upload files to a directory**
+// @Description
+// @Description - one or more files can be uploaded
+// @Description - existing uploaded are overwritten
+// @Description
+// @Description **Example:**
+// @Description  ```
+// @Description $ curl -X POST -F file=@aptly_0.9~dev+217+ge5d646c_i386.deb http://localhost:8080/api/files/aptly-0.9
+// @Description ["aptly-0.9/aptly_0.9~dev+217+ge5d646c_i386.deb"]
+// @Description  ```
 // @Tags Files
 // @Accept multipart/form-data
 // @Param dir path string true "Directory to upload files to. Created if does not exist"
@@ -132,8 +146,14 @@ func apiFilesUpload(c *gin.Context) {
 	c.JSON(200, stored)
 }
 
-// @Summary List files in directory
-// @Description **Returns list of files in directory**
+// @Summary List Files
+// @Description **Show uploaded files in upload directory**
+// @Description
+// @Description **Example:**
+// @Description  ```
+// @Description $ curl http://localhost:8080/api/files/aptly-0.9
+// @Description ["aptly_0.9~dev+217+ge5d646c_i386.deb"]
+// @Description  ```
 // @Tags Files
 // @Produce json
 // @Param dir path string true "Directory to list"
@@ -179,7 +199,13 @@ func apiFilesListFiles(c *gin.Context) {
 }
 
 // @Summary Delete Directory
-// @Description **Deletes all files in upload directory and directory itself**
+// @Description **Delete upload directory and uploaded files within**
+// @Description
+// @Description **Example:**
+// @Description  ```
+// @Description $ curl -X DELETE http://localhost:8080/api/files/aptly-0.9
+// @Description {}
+// @Description  ```
 // @Tags Files
 // @Produce json
 // @Param dir path string true "Directory"
@@ -200,8 +226,14 @@ func apiFilesDeleteDir(c *gin.Context) {
 	c.JSON(200, gin.H{})
 }
 
-// @Summary Delete File in Directory
-// @Description **Delete single file in directory**
+// @Summary Delete File
+// @Description **Delete a uploaded file in upload directory**
+// @Description
+// @Description **Example:**
+// @Description  ```
+// @Description $ curl -X DELETE http://localhost:8080/api/files/aptly-0.9/aptly_0.9~dev+217+ge5d646c_i386.deb
+// @Description {}
+// @Description  ```
 // @Tags Files
 // @Produce json
 // @Param dir path string true "Directory to delete from"
diff --git a/docs/Files.md b/docs/Files.md
index 84ed30a3..616a64ac 100644
--- a/docs/Files.md
+++ b/docs/Files.md
@@ -1,84 +1,12 @@
 # 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).
 
-All uploaded files are stored under `<rootDir>/upload` directory (see [configuration](/doc/configuration)).
-This directory would be created automatically if it doesn't exist.
+In order to add debian package files to a local repository, files are first uploaded to a temporary directory.
+Then the directory (or a specific file within) is added to a repository. After adding to a repositorty, the directory resp. files are removed bt default.
 
-Uploaded files are grouped by directories to support concurrent uploads from multiple
-package sources. Local repos add API can operate on directory (adding all files from directory) or
-on individual package files. By default, all successfully added package files would be removed.
+All uploaded files are stored under `<rootDir>/upload/<tempdir>` directory.
 
-### List Directories
+For concurrent uploads from CI/CD pipelines, make sure the tempdir is unique.
 
-`GET /api/files`
-
-List all directories.
-
-Response: list of directory names.
-
-Example:
-
-    $ curl http://localhost:8080/api/files
-    ["aptly-0.9"]
-
-### Upload File(s)
-
-`POST /api/files/:dir`
-
-Parameter `:dir` is upload directory name. Directory would be created if it doesn't exist.
-
-Any number of files can be uploaded in one call, aptly would preserve filenames. No check is performed
-if existing uploaded would be overwritten.
-
-Response: list of uploaded files as `:dir/:file`.
-
-Example:
-
-    $ curl -X POST -F file=@aptly_0.9~dev+217+ge5d646c_i386.deb http://localhost:8080/api/files/aptly-0.9
-    ["aptly-0.9/aptly_0.9~dev+217+ge5d646c_i386.deb"]
-
-### List Files in Directory
-
-`GET /api/files/:dir`
-
-Returns list of files in directory.
-
-Response: list of filenames.
-
-HTTP Errors:
-
- Code     | Description
-----------|-------------------------
- 404      | directory doesn't exist
-
-Example:
-
-    $ curl http://localhost:8080/api/files/aptly-0.9
-    ["aptly_0.9~dev+217+ge5d646c_i386.deb"]
-
-
-### Delete Directory
-
-`DELETE /api/files/:dir`
-
-Deletes all files in upload directory and directory itself.
-
-Example:
-
-    $ curl -X DELETE http://localhost:8080/api/files/aptly-0.9
-    {}
-
-### Delete File in Directory
-
-`DELETE /api/files/:dir/:file`
-
-Delete single file in directory.
-
-Example:
-
-    $ curl -X DELETE http://localhost:8080/api/files/aptly-0.9/aptly_0.9~dev+217+ge5d646c_i386.deb
-    {}
 
 </div>
diff --git a/docs/Repos.md b/docs/Repos.md
index aeffda24..05960c03 100644
--- a/docs/Repos.md
+++ b/docs/Repos.md
@@ -1,11 +1,9 @@
 # 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.
-Multiple versions of the same package could be added to the repository.
-In order to capture current repository state, [create snapshot](/doc/aptly/snapshot/create/).
+A local repository is a collection of versionned packages (usually custom packages created internally).
 
-Local repositories could be published either [directly](/doc/aptly/publish/repo/)
-or from [snapshot](/doc/aptly/publish/snapshot).
+Packages can be added, removed, moved or copied between repos.
+
+Local repositories can be published (either directly or via snapshot) to be used a APT source on a debian based system.
 </div>
 
diff --git a/docs/docs.html b/docs/docs.html
index 142791ed..d057ee1d 100644
--- a/docs/docs.html
+++ b/docs/docs.html
@@ -167,7 +167,7 @@ window.onload = function() {
 
   window.ui = ui
 
-  setTimeout(collapseAll, 700);
+  setTimeout(collapseAll, 50);
 }
 </script>
 </body>