Better structure for organizing images in documentation
Right now images aren't updated very often because there are a ton of them. It's also difficult to find all the image directories that are scattered throughout the documentation.
I'd like to propose reorganizing this so we have a doc/images/ directory to house all images used throughout the documentation. This has a few benefits:
- Easier to find all images
- Easier to determine which images are outdated and need updating
- Easier to automate screenshots with a rake task (see https://gitlab.com/gitlab-org/gitlab-ce/issues/4297#note_4371669)
- If Git ever introduces directory-specific shallow cloning, this'd work great for it
Here's the current doc directory structure:
├── README.md
├── administration
│ ├── auth
│ │ ├── README.md
│ │ └── ldap.md
│ ├── container_registry.md
│ ├── environment_variables.md
│ ├── high_availability
│ │ ├── README.md
│ │ ├── database.md
│ │ ├── gitlab.md
│ │ ├── load_balancer.md
│ │ ├── nfs.md
│ │ └── redis.md
│ ├── housekeeping.md
│ ├── img
│ │ ├── high_availability
│ │ │ ├── active-active-diagram.png
│ │ │ └── active-passive-diagram.png
│ │ └── housekeeping_settings.png
│ ├── repository_checks.md
│ ├── restart_gitlab.md
│ └── troubleshooting
│ └── sidekiq.md
├── api
│ ├── README.md
│ ├── branches.md
│ ├── build_triggers.md
│ ├── build_variables.md
│ ├── builds.md
│ ├── commits.md
│ ├── deploy_key_multiple_projects.md
│ ├── deploy_keys.md
│ ├── groups.md
│ ├── issues.md
│ ├── keys.md
│ ├── labels.md
│ ├── licenses.md
│ ├── merge_requests.md
│ ├── milestones.md
│ ├── namespaces.md
│ ├── notes.md
│ ├── oauth2.md
│ ├── project_snippets.md
│ ├── projects.md
│ ├── repositories.md
│ ├── repository_files.md
│ ├── runners.md
│ ├── services.md
│ ├── session.md
│ ├── settings.md
│ ├── system_hooks.md
│ ├── tags.md
│ └── users.md
├── ci
│ ├── README.md
│ ├── api
│ │ ├── README.md
│ │ ├── builds.md
│ │ └── runners.md
│ ├── build_artifacts
│ │ ├── README.md
│ │ └── img
│ │ ├── build_artifacts_browser.png
│ │ └── build_artifacts_browser_button.png
│ ├── docker
│ │ ├── README.md
│ │ ├── using_docker_build.md
│ │ └── using_docker_images.md
│ ├── enable_or_disable_ci.md
│ ├── examples
│ │ ├── README.md
│ │ ├── deployment
│ │ │ └── README.md
│ │ ├── php.md
│ │ ├── test-and-deploy-python-application-to-heroku.md
│ │ ├── test-and-deploy-ruby-application-to-heroku.md
│ │ └── test-clojure-application.md
│ ├── img
│ │ ├── builds_tab.png
│ │ └── features_settings.png
│ ├── permissions
│ │ └── README.md
│ ├── quick_start
│ │ ├── README.md
│ │ └── img
│ │ ├── build_log.png
│ │ ├── builds_status.png
│ │ ├── new_commit.png
│ │ ├── runners_activated.png
│ │ ├── single_commit_status_pending.png
│ │ └── status_pending.png
│ ├── runners
│ │ ├── README.md
│ │ ├── project_specific.png
│ │ ├── shared_runner.png
│ │ └── shared_to_specific_admin.png
│ ├── services
│ │ ├── README.md
│ │ ├── docker-services.md
│ │ ├── mysql.md
│ │ ├── postgres.md
│ │ └── redis.md
│ ├── ssh_keys
│ │ └── README.md
│ ├── triggers
│ │ ├── README.md
│ │ └── img
│ │ ├── builds_page.png
│ │ ├── trigger_single_build.png
│ │ ├── trigger_variables.png
│ │ └── triggers_page.png
│ ├── variables
│ │ └── README.md
│ └── yaml
│ └── README.md
├── container_registry
│ ├── README.md
│ └── img
│ ├── container_registry.png
│ └── project_feature.png
├── customization
│ ├── branded_login_page
│ │ ├── appearance.png
│ │ ├── custom_sign_in.png
│ │ └── default_login_page.png
│ ├── branded_login_page.md
│ ├── issue_closing.md
│ ├── libravatar.md
│ └── welcome_message.md
├── development
│ ├── README.md
│ ├── architecture.md
│ ├── ci_setup.md
│ ├── code_review.md
│ ├── db_dump.md
│ ├── doc_styleguide.md
│ ├── gitlab_diagram_overview.odg
│ ├── gitlab_diagram_overview.png
│ ├── gotchas.md
│ ├── instrumentation.md
│ ├── migration_style_guide.md
│ ├── omnibus.md
│ ├── performance.md
│ ├── profiling.md
│ ├── rake_tasks.md
│ ├── scss_styleguide.md
│ ├── shared_files.md
│ ├── shell_commands.md
│ ├── sidekiq_debugging.md
│ ├── sql.md
│ ├── testing.md
│ └── ui_guide.md
├── downgrade_ee_to_ce
│ └── README.md
├── gitlab-basics
│ ├── README.md
│ ├── add-file.md
│ ├── add-image.md
│ ├── add-merge-request.md
│ ├── basic-git-commands.md
│ ├── basicsimages
│ │ ├── add_new_merge_request.png
│ │ ├── add_sshkey.png
│ │ ├── branch_info.png
│ │ ├── branch_name.png
│ │ ├── branches.png
│ │ ├── button-create-mr.png
│ │ ├── click-on-new-group.png
│ │ ├── commit_changes.png
│ │ ├── commit_message.png
│ │ ├── commits.png
│ │ ├── compare_branches.png
│ │ ├── create_file.png
│ │ ├── create_group.png
│ │ ├── edit_file.png
│ │ ├── file_located.png
│ │ ├── file_name.png
│ │ ├── find_file.png
│ │ ├── find_group.png
│ │ ├── fork.png
│ │ ├── group_info.png
│ │ ├── groups.png
│ │ ├── https.png
│ │ ├── image_file.png
│ │ ├── issue_title.png
│ │ ├── issues.png
│ │ ├── key.png
│ │ ├── merge_requests.png
│ │ ├── new_issue.png
│ │ ├── new_merge_request.png
│ │ ├── new_project.png
│ │ ├── newbranch.png
│ │ ├── paste_sshkey.png
│ │ ├── profile_settings.png
│ │ ├── project_info.png
│ │ ├── public_file_link.png
│ │ ├── select-group.png
│ │ ├── select-group2.png
│ │ ├── select_branch.png
│ │ ├── select_project.png
│ │ ├── settings.png
│ │ ├── shh_keys.png
│ │ ├── submit_new_issue.png
│ │ ├── title_description_mr.png
│ │ └── white_space.png
│ ├── command-line-commands.md
│ ├── create-branch.md
│ ├── create-group.md
│ ├── create-issue.md
│ ├── create-project.md
│ ├── create-your-ssh-keys.md
│ ├── fork-project.md
│ └── start-using-git.md
├── hooks
│ └── custom_hooks.md
├── incoming_email
│ ├── README.md
│ └── postfix.md
├── install
│ ├── README.md
│ ├── database_mysql.md
│ ├── installation.md
│ ├── redis.md
│ ├── relative_url.md
│ ├── requirements.md
│ └── structure.md
├── integration
│ ├── README.md
│ ├── akismet.md
│ ├── auth0.md
│ ├── azure.md
│ ├── bitbucket.md
│ ├── cas.md
│ ├── crowd.md
│ ├── external-issue-tracker.md
│ ├── facebook.md
│ ├── github.md
│ ├── gitlab.md
│ ├── gmail_action_buttons_for_gitlab.md
│ ├── google.md
│ ├── img
│ │ ├── akismet_settings.png
│ │ ├── enabled-oauth-sign-in-sources.png
│ │ ├── facebook_api_keys.png
│ │ ├── facebook_app_settings.png
│ │ ├── facebook_website_url.png
│ │ ├── github_app.png
│ │ ├── gitlab_app.png
│ │ ├── gmail_action_buttons_for_gitlab.png
│ │ ├── google_app.png
│ │ ├── oauth_provider_admin_application.png
│ │ ├── oauth_provider_application_form.png
│ │ ├── oauth_provider_application_id_secret.png
│ │ ├── oauth_provider_authorized_application.png
│ │ ├── oauth_provider_user_wide_applications.png
│ │ ├── twitter_app_api_keys.png
│ │ └── twitter_app_details.png
│ ├── jira.md
│ ├── ldap.md
│ ├── oauth_provider.md
│ ├── omniauth.md
│ ├── recaptcha.md
│ ├── saml.md
│ ├── shibboleth.md
│ ├── slack.md
│ └── twitter.md
├── intro
│ └── README.md
├── legal
│ ├── README.md
│ ├── corporate_contributor_license_agreement.md
│ └── individual_contributor_license_agreement.md
├── logs
│ └── logs.md
├── markdown
│ ├── img
│ │ └── logo.png
│ └── markdown.md
├── migrate_ci_to_ce
│ └── README.md
├── monitoring
│ ├── health_check.md
│ ├── img
│ │ └── health_check_token.png
│ └── performance
│ ├── gitlab_configuration.md
│ ├── grafana_configuration.md
│ ├── img
│ │ ├── grafana_dashboard_dropdown.png
│ │ ├── grafana_dashboard_import.png
│ │ ├── grafana_data_source_configuration.png
│ │ ├── grafana_data_source_empty.png
│ │ ├── grafana_save_icon.png
│ │ └── metrics_gitlab_configuration_settings.png
│ ├── influxdb_configuration.md
│ ├── influxdb_schema.md
│ └── introduction.md
├── operations
│ ├── README.md
│ ├── cleaning_up_redis_sessions.md
│ ├── moving_repositories.md
│ ├── sidekiq_memory_killer.md
│ └── unicorn.md
├── permissions
│ └── permissions.md
├── profile
│ ├── 2fa.png
│ ├── 2fa_auth.png
│ ├── README.md
│ ├── preferences.md
│ └── two_factor_authentication.md
├── project_services
│ ├── bamboo.md
│ ├── builds_emails.md
│ ├── hipchat.md
│ ├── img
│ │ ├── builds_emails_service.png
│ │ ├── jira_add_gitlab_commit_message.png
│ │ ├── jira_add_user_to_group.png
│ │ ├── jira_create_new_group.png
│ │ ├── jira_create_new_group_name.png
│ │ ├── jira_create_new_user.png
│ │ ├── jira_group_access.png
│ │ ├── jira_issue_closed.png
│ │ ├── jira_issue_reference.png
│ │ ├── jira_issues_workflow.png
│ │ ├── jira_merge_request_close.png
│ │ ├── jira_project_name.png
│ │ ├── jira_reference_commit_message_in_jira_issue.png
│ │ ├── jira_service.png
│ │ ├── jira_service_close_issue.png
│ │ ├── jira_service_page.png
│ │ ├── jira_submit_gitlab_merge_request.png
│ │ ├── jira_user_management_link.png
│ │ ├── jira_workflow_screenshot.png
│ │ ├── redmine_configuration.png
│ │ └── services_templates_redmine_example.png
│ ├── irker.md
│ ├── jira.md
│ ├── project_services.md
│ ├── redmine.md
│ └── services_templates.md
├── public_access
│ └── public_access.md
├── raketasks
│ ├── README.md
│ ├── backup_hrz.png
│ ├── backup_restore.md
│ ├── check.md
│ ├── check_repos_output.png
│ ├── cleanup.md
│ ├── features.md
│ ├── import.md
│ ├── list_repos.md
│ ├── maintenance.md
│ ├── user_management.md
│ └── web_hooks.md
├── security
│ ├── README.md
│ ├── crime_vulnerability.md
│ ├── img
│ │ └── two_factor_authentication_settings.png
│ ├── information_exclusivity.md
│ ├── password_length_limits.md
│ ├── rack_attack.md
│ ├── reset_root_password.md
│ ├── two_factor_authentication.md
│ ├── user_email_confirmation.md
│ ├── user_file_uploads.md
│ └── webhooks.md
├── ssh
│ └── README.md
├── system_hooks
│ └── system_hooks.md
├── update
│ ├── 2.6-to-3.0.md
│ ├── 2.9-to-3.0.md
│ ├── 3.0-to-3.1.md
│ ├── 3.1-to-4.0.md
│ ├── 4.0-to-4.1.md
│ ├── 4.1-to-4.2.md
│ ├── 4.2-to-5.0.md
│ ├── 5.0-to-5.1.md
│ ├── 5.1-to-5.2.md
│ ├── 5.1-to-5.4.md
│ ├── 5.1-to-6.0.md
│ ├── 5.2-to-5.3.md
│ ├── 5.3-to-5.4.md
│ ├── 5.4-to-6.0.md
│ ├── 6.0-to-6.1.md
│ ├── 6.1-to-6.2.md
│ ├── 6.2-to-6.3.md
│ ├── 6.3-to-6.4.md
│ ├── 6.4-to-6.5.md
│ ├── 6.5-to-6.6.md
│ ├── 6.6-to-6.7.md
│ ├── 6.7-to-6.8.md
│ ├── 6.8-to-6.9.md
│ ├── 6.9-to-7.0.md
│ ├── 6.x-or-7.x-to-7.14.md
│ ├── 7.0-to-7.1.md
│ ├── 7.1-to-7.2.md
│ ├── 7.10-to-7.11.md
│ ├── 7.11-to-7.12.md
│ ├── 7.12-to-7.13.md
│ ├── 7.13-to-7.14.md
│ ├── 7.14-to-8.0.md
│ ├── 7.2-to-7.3.md
│ ├── 7.3-to-7.4.md
│ ├── 7.4-to-7.5.md
│ ├── 7.5-to-7.6.md
│ ├── 7.6-to-7.7.md
│ ├── 7.7-to-7.8.md
│ ├── 7.8-to-7.9.md
│ ├── 7.9-to-7.10.md
│ ├── 8.0-to-8.1.md
│ ├── 8.1-to-8.2.md
│ ├── 8.2-to-8.3.md
│ ├── 8.3-to-8.4.md
│ ├── 8.4-to-8.5.md
│ ├── 8.5-to-8.6.md
│ ├── 8.6-to-8.7.md
│ ├── 8.7-to-8.8.md
│ ├── README.md
│ ├── mysql_to_postgresql.md
│ ├── patch_versions.md
│ ├── restore_after_failure.md
│ └── upgrader.md
├── web_hooks
│ ├── ssl.png
│ └── web_hooks.md
└── workflow
├── README.md
├── add-user
│ ├── add-user.md
│ └── img
│ ├── add_new_user_to_project_settings.png
│ ├── add_user_email_accept.png
│ ├── add_user_email_ready.png
│ ├── add_user_email_search.png
│ ├── add_user_give_permissions.png
│ ├── add_user_import_members_from_another_project.png
│ ├── add_user_imported_members.png
│ ├── add_user_list_members.png
│ ├── add_user_members_menu.png
│ └── add_user_search_people.png
├── authorization_for_merge_requests.md
├── award_emoji.md
├── award_emoji.png
├── cherry_pick_changes.md
├── ci_mr.png
├── close_issue_mr.png
├── environment_branches.png
├── file_finder.md
├── forking
│ ├── branch_select.png
│ └── merge_request.png
├── forking_workflow.md
├── four_stages.png
├── git_pull.png
├── gitdashflow.png
├── github_flow.png
├── gitlab_flow.md
├── gitlab_flow.png
├── good_commit.png
├── groups
│ ├── add_member_to_group.png
│ ├── group_dashboard.png
│ ├── group_with_two_projects.png
│ ├── max_access_level.png
│ ├── new_group_button.png
│ ├── new_group_form.png
│ ├── other_group_sees_shared_project.png
│ ├── override_access_level.png
│ ├── project_members_via_group.png
│ ├── share_project_with_groups.png
│ └── transfer_project.png
├── groups.md
├── img
│ ├── award_emoji_select.png
│ ├── award_emoji_votes_least_popular.png
│ ├── award_emoji_votes_most_popular.png
│ ├── award_emoji_votes_sort_options.png
│ ├── cherry_pick_changes_commit.png
│ ├── cherry_pick_changes_commit_modal.png
│ ├── cherry_pick_changes_mr.png
│ ├── cherry_pick_changes_mr_modal.png
│ ├── file_finder_find_button.png
│ ├── file_finder_find_file.png
│ ├── forking_workflow_choose_namespace.png
│ ├── forking_workflow_fork_button.png
│ ├── forking_workflow_path_taken_error.png
│ ├── new_branch_from_issue.png
│ ├── revert_changes_commit.png
│ ├── revert_changes_commit_modal.png
│ ├── revert_changes_mr.png
│ ├── revert_changes_mr_modal.png
│ ├── todos_icon.png
│ ├── todos_index.png
│ ├── web_editor_new_branch_dropdown.png
│ ├── web_editor_new_branch_page.png
│ ├── web_editor_new_directory_dialog.png
│ ├── web_editor_new_directory_dropdown.png
│ ├── web_editor_new_file_dropdown.png
│ ├── web_editor_new_file_editor.png
│ ├── web_editor_new_push_widget.png
│ ├── web_editor_new_tag_dropdown.png
│ ├── web_editor_new_tag_page.png
│ ├── web_editor_start_new_merge_request.png
│ ├── web_editor_upload_file_dialog.png
│ └── web_editor_upload_file_dropdown.png
├── importing
│ ├── README.md
│ ├── bitbucket_importer
│ │ ├── bitbucket_import_grant_access.png
│ │ ├── bitbucket_import_new_project.png
│ │ ├── bitbucket_import_select_bitbucket.png
│ │ └── bitbucket_import_select_project.png
│ ├── fogbugz_importer
│ │ ├── fogbugz_import_finished.png
│ │ ├── fogbugz_import_login.png
│ │ ├── fogbugz_import_select_fogbogz.png
│ │ ├── fogbugz_import_select_project.png
│ │ └── fogbugz_import_user_map.png
│ ├── gitlab_importer
│ │ ├── importer.png
│ │ └── new_project_page.png
│ ├── img
│ │ ├── import_projects_from_github_importer.png
│ │ └── import_projects_from_github_new_project_page.png
│ ├── import_projects_from_bitbucket.md
│ ├── import_projects_from_fogbugz.md
│ ├── import_projects_from_github.md
│ ├── import_projects_from_gitlab_com.md
│ └── migrating_from_svn.md
├── labels
│ ├── label1.png
│ ├── label2.png
│ └── label3.png
├── labels.md
├── lfs
│ ├── lfs_administration.md
│ └── manage_large_binaries_with_git_lfs.md
├── merge_commits.png
├── merge_request.png
├── merge_requests
│ ├── commit_compare.png
│ ├── merge_request_diff.png
│ └── merge_request_diff_without_whitespace.png
├── merge_requests.md
├── merge_when_build_succeeds
│ ├── enable.png
│ └── status.png
├── merge_when_build_succeeds.md
├── messy_flow.png
├── milestones
│ ├── form.png
│ └── group_form.png
├── milestones.md
├── mr_inline_comments.png
├── notifications
│ └── settings.png
├── notifications.md
├── production_branch.png
├── project_features.md
├── protected_branches
│ ├── protected_branches1.png
│ └── protected_branches2.png
├── protected_branches.md
├── rebase.png
├── release_branches.png
├── releases
│ ├── new_tag.png
│ └── tags.png
├── releases.md
├── remove_checkbox.png
├── revert_changes.md
├── share_projects_with_other_groups.md
├── share_with_group.md
├── share_with_group.png
├── shortcuts.md
├── shortcuts.png
├── timezone.md
├── todos.md
├── web_editor.md
├── wip_merge_requests
│ ├── blocked_accept_button.png
│ ├── mark_as_wip.png
│ └── unmark_as_wip.png
├── wip_merge_requests.md
└── workflow.md
81 directories, 511 filesBy my count, there are 25 directories which contain only images, and a significant number of them are not named img, images, or anything that would suggest an images folder.
I think there are two ways we can do this, I'm not sure which one is better.
All images in one directory, maybe this won't scale, but it will have less breakage if a page moves sections:
└── images
├── image1.png
├── image2.png
└─── image3.pngEssentially map the directory structure of the doc directory:
└── images
├── section
│ ├── image1.png
│ └── image2.png
└─── section2
└── image3.pngAnd of course, this should be done in parts (10 images at a time? 20? Maybe just do x number of directories in each MR?) rather than all at once.
cc: @axil