Skip to content

[Doc]: Move non user guide related content out of /users #27396

Description

@story645

Problem

Given that /doc is now the root folder/index, a lot of the indexing that used to live on the users index page is now on the doc/index and it's a little easier to find things when the code structure matches the indexing. Also currently it's a little hard to define what we mean by user guide and scoping the contents of the folder can help in defining the purpose.

Suggested improvement

  • /users/project -> /doc/project
  • /users/installing->doc/installing
  • /users/{generate_credits, github_stats, *_whats_new, release_notes*} -> /doc/release
  • `/getting_started/* -> quickstart guide
  • /users/users_explain/* -> /users

Consensus

As discussed on the call, the rough consensus is this organization makes sense but should be done in stages, roughly one folder at a time. Largest concern was getting all the redirects correct and making sure that any links and instructions related to those docs are updated as needed. The stages are:

  • move the /project folder up ->Moved /users/project to /doc/project #27560
  • move the /installing folder up -> (might be a good chance to change the name to install?) Move doc/users/installing/ to doc/install/ #27747
  • move the release related folders and docs {generate_credits, github_stats, _whats_new, release_notes} into a folder and up one level
  • merge the contents in users/getting_started into the gallery/users_explain/quickstart guide and remove the getting_started folder
  • remove doc/users and rename gallery/users_explain to users

Motivation

  • currently /users/index/ is scoped to users_explain + getting_started, this would be matching structure to stated structure, in turn making it easier to find where a doc is to change it
    • also means we can remove the symlink, which currently trips folks up when trying to edit documents under /user
  • the contents under /project are I think version independent (though we may want to keep the versioning on the site b/c the historicity is also important) but also for the most part should not be changed w/o consensus/streering-council sign off and it's a little easier to communicate that if it's not lumped with other user docs
  • I'm half/half on /doc/install b/c I understand why it would be inside a users guide but we also write those documents as a more general installation guide/reference for both
  • there are a lot of files related to the release process and unlike /api/changes it's not clear why they are here.

Activity

  1. self-assigned this
    on Dec 13, 2023
  2. shriyakalakata commented on Dec 22, 2023

    @shriyakalakata
    Contributor

    @story645 I can start working on this now!

  3. added this to the v3.9.0 milestone on Feb 2, 2024
  4. modified the milestones: v3.9.0, future releases on Apr 4, 2024
  5. QuLogic commented on Apr 4, 2024

    @QuLogic
    Member

    I assume the other stages still need to be done.

  6. reopened this on Apr 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions