Skip to content

Break up uploads developer docs into 3 sections

Matthias Käppler requested to merge 351213-restructure-uploads-doc into master

What does this MR do?

WorkingGroupObjectStorage is looking to improve our developer documentation around uploads and the use of Object Storage: #351213 (closed). These are not docs meant for users, but GitLab contributors trying to better understand the complexities of uploads at GitLab.

I would like to improve this incrementally. To that end, I have left the existing text/content untouched, and merely broke it down into 3 sections/files, that should set the stage better and address different target audiences:

  • Part 1: Historic context around uploads and “setting the stage”, e.g.
    • How are uploads handled in Rails normally
    • What are the problems with that
    • Why we added direct uploads, and our move towards Object Storage
    • Target audience: Developers looking for reasons behind the current implementation, but optional read.
  • Part 2: Explain the current implementation of uploads across Workhorse and Rails
    • Establish common language around uploads
    • How does an upload request propagate through the system
    • What exactly happens in Workhorse
    • What exactly happens in Rails
    • Target audience: Developers looking to work on Workhorse or Rails upload logic, or folks who are just curious about how it works.
  • Part 3: How to add new uploads. This should focus purely on “how” and not “why” and contain code examples or links to MRs that have done this before. This would expand the section https://docs.gitlab.com/ee/development/uploads.html#how-to-add-a-new-upload-route
    • Target audience: Developers looking to add a new upload resource, without feeling the need to know how it works internally.

The current content is has probably never been copy edited, since it reads a bit odd at times. I would like to ask reviewers to ignore this for now, since we are looking to rewrite most of it anyway.

Preview: http://main-ee-80392.178.62.207.141.nip.io/ee/development/uploads/index.html

Related issues

Author's checklist

If you are only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Review checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
  • Ensure a release milestone is set.
Edited by Marcin Sedlak-Jakubowski

Merge request reports