Refactor Git docs
Problem to solve
Our Git documentation has grown organically over time, and it's time to look at the entire suite of Git documentation at https://docs.gitlab.com/ee/topics/git/ and make sure it's a good resource for our customers that use Git regularly with GitLab.
Further details
Our current Git documentation is located in the following locations the gitlab
project:
doc/topics/git
doc/tutorials/make_first_git_commit
doc/gitlab-basics
doc/user/project/push_options.md
Our current Git menu structure is:
Proposal
To ensure that our Git documentation is a coherent whole, and is easily navigable and searchable, this issue proposes:
- Have (or create) these pages (existing relevant pages in brackets):
- Learn Git (https://docs.gitlab.com/ee/topics/git/)
- Get started (https://docs.gitlab.com/ee/topics/git/get_started.html)
- Install Git (https://docs.gitlab.com/ee/topics/git/how_to_install_git/)
- Tutorial: Create your first commit (https://docs.gitlab.com/ee/tutorials/make_first_git_commit/)
- Clone a repository to your local machine (https://docs.gitlab.com/ee/topics/git/clone.html)
- Create a branch for your changes (https://docs.gitlab.com/ee/topics/git/branch.html)
- Stash changes for later (https://docs.gitlab.com/ee/gitlab-basics/add-file.html)
- Stage, commit, and push changes (https://docs.gitlab.com/ee/gitlab-basics/add-file.html)
- Undo commits (https://docs.gitlab.com/ee/topics/git/undo.html)
- Tutorial: Change your commit message (https://docs.gitlab.com/ee/tutorials/update_commit_messages/)
- Merge your branch into the main branch (discuss merge options)
- Learn Git (https://docs.gitlab.com/ee/topics/git/)
- Create a separate reference page (probably this: https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html because we already have a new
get_started.md
page) for all the commands we're using, and cross link to it. The page should be structured like the Reference page template. - Incorporate content from these pages and remove them:
-
https://docs.gitlab.com/ee/topics/git/partial_clone.html (could add to https://docs.gitlab.com/ee/topics/git/clone.html) -
https://docs.gitlab.com/ee/topics/git/git_rebase.html -
https://docs.gitlab.com/ee/gitlab-basics/feature_branch_workflow.html -
https://docs.gitlab.com/ee/user/project/push_options.html -
https://docs.gitlab.com/ee/topics/git/troubleshooting_git.html (we'll probably keep this one as is)
-
- Move these files around to be together in a single directory in the docs suite.
Reference page template
# Git commands
Learn more about the most commonly used Git commands.
## `git add`
Use `git add` to do xyz.
### Example
code here
For more information, see ... (link).
## `git commit`
Use `git commit` to do ...
### Example
code here
For more information, see .. (link).
Who can address the issue
Members of the Technical Writing Team
Edited by Evan Read