Optimize contribution docs organization for onboarding

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Problem

Our documentation on contribute to GitLab is not organized by concerns and it's not very user-friendly to newcomers, community contributors and onboarding team members.

There are several issues that have been identified, also taking feedback from engineers being on-boarded:

• Various levels of concerns and abstractions are mixed together: Architecture and Development Rake tasks
• Documentation related to workflow processes (e.g. Code review guidelines) is mixed with design patterns and frameworks (e.g. DeclarativePolicy)
• Domain-specific development docs (e.g. Git object deduplication) are mixed with cross cutting concerns (e.g. Logging)
• Wrong nesting introduces ambiguity. For example: Feature development > Code comments (is it about the commenting feature or a coding style?)

This lack of organization into clear abstractions and concerns is a real technical debt because it makes our docs harder to keep organized and it's not clear where new additions should go.

There are other minor issues:

• Inconsistent terminology: guide(s) vs guideline(s)
• many files are defined in a flat structure and then indented as links to the documentation. But the structure in the page may not reflect the structure in the repository.

Proposal

I went through most of the high-level pages/sections in our Contribute to GitLab docs and tried to restructure those slightly differently. The goal is to have a clear top-down navigation of our guidelines with a clear place for any kind of documentation related to contributing.

.
└── Contribute to Gitlab/
    ├── Architecture
    ├── Contribution process/
    │   ├── Changelog entries
    │   ├── Code review guidelines
    │   ├── Community roles
    │   ├── Deprecation guidelines
    │   ├── Requirements/
    │   │   └── ChatOps on Gitlab.com
    │   ├── Issues workflow
    │   ├── Merge request workflow
    │   └── Secure partner onboarding process
    ├── Development Environment/
    │   ├── GDK
    │   ├── Development Rake tasks
    │   └── Windows development
    └── Development guides/
        ├── General/
        │   ├── Observability/
        │   │   ├── Prometheuse metrics
        │   │   ├── Observability for stage groups
        │   │   ├── Kibana
        │   │   └── Sentry
        │   ├── Danger bot
        │   ├── FIPS compliance
        │   ├── Gotchas - we should probably have a better way
        │   ├── Internationalization (i18n)
        │   ├── Experiments
        │   ├── Feature flags for GitLab development
        │   └── Product intelligence guides
        ├── Backend/
        │   ├── Software design and coding guides/
        │   │   ├── directory structure
        │   │   ├── Guidelines for reusing abstractions
        │   │   ├── Implementing Enterprises Edition features
        │   │   ├── Renaming features
        │   │   ├── Performance guides
        │   │   └── Secure coding guides
        │   ├── Tools and cross-cutting concerns/
        │   │   ├── GitLab EventStore
        │   │   ├── GitLab utilities
        │   │   ├── Logging
        │   │   ├── Permissions
        │   │   ├── Dealing with email/mailers
        │   │   ├── Uploads development guide
        │   │   ├── Sidekiq guidelines
        │   │   ├── Feature categorization
        │   │   └── Application limits
        │   ├── Ruby Style guides/
        │   │   ├── Newlines style guide
        │   │   ├── Code comments
        │   │   └── Avoid modules with instance variables
        │   ├── Ruby & Rails/
        │   │   ├── Gemfile guidelines
        │   │   ├── Rails initializers
        │   │   ├── Mass Inserting Models
        │   │   ├── Routing
        │   │   ├── Ruby upgrade guidelines
        │   │   ├── Rails update guidelines
        │   │   └── Ruby 3 gotchas
        │   └── Troubuleshooting/
        │       ├── Pry debugging
        │       └── Sidekiq debugging
        ├── Frontend/
        │   └── ...
        ├── Database/
        │   └── ...
        ├── Documentation/
        │   └── ...
        ├── API/
        │   ├── REST API style guide
        │   └── GraphQL API style guide
        ├── Testing/
        │   ├── Testing (contract)
        │   └── Testing (end to end)
        └── Domain-specific guides       # <-- should be categorized by Stage or feature category because there are many of them/
            ├── Import and Export
            ├── Kubenetes integration guidelines
            ├── Issuable-like Rails models
            ├── Work items and work item types
            ├── Geo development
            ├── Working with Gitaly
            ├── Working with merge request diffs
            ├── Approval rules
            ├── Git/
            │   ├── Git LFS
            │   └── How Git object deduplication works in GitLab
            ├── Repository mirroring
            ├── Elasticsearch integration docs
            ├── Auto DevOps development guide
            ├── Code intelligence
            └── Integration guides

All our docs inside Contribute to GitLab > Development guides > Domain-specific guides should be organized better, perhaps by Stage or Feature Category so readers can zoom in the domain area they are interested in contributing.