chore:create doc that coveres history and deleted docs

newrelic · Dec 15, 2021 · e5a1661 · e5a1661
1 parent 7c9e5b5
commit e5a1661
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 36 deletions.
diff --git a/src/content/docs/style-guide/writing-docs/writer-workflow/github-history.mdx b/src/content/docs/style-guide/writing-docs/writer-workflow/github-history.mdx
@@ -0,0 +1,92 @@
+---
+title: GitHub history and deleted files
+topics:
+  - Tech writer style guide
+  - How to use GitHub
+redirects: 
+  - /docs/style-guide/writer-workflow/github-intro
+---
+
+GitHub's version control features allow us to see the complete history of a doc, access a doc at any point in time, and find deleted docs without manual backups.
+
+## Check the edit history of a doc or file [#doc-history]
+Use any of these options to check or "diff" the history of a file.
+
+**Option 1: GitHub history tab**
+1. Navigate to the doc on the doc site and click **Edit page** in the right nav.
+2. Click **History** in the top right corner of the doc. 
+
+**Option 2: githistory.xy**
+1. Navigate to your specific file on GitHub.com:
+  ```
+  https://github.com/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx
+  ```
+2. In the url, replace `github.com` with `github.githistory.xyz`:
+  ```
+  https://github.githistory.xyz/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx
+  ```
+
+3. It will take you to a site which presents the visual history of that specific file. You can view changes by clicking through the commit history at the top of your page.
+
+**Option 3: Git blame**
+
+Follow [GitHub's documentation](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file).
+
+Alternatively, you can use the following command in your terminal:
+```
+git log --follow "**/file_name_here.mdx"
+```
+This will output the commit history of that file. By default, it only shows the first few commits. You can scroll by pressing Return multiple times.
+
+For example, to find the commit history for  `vmware-vsphere-monitoring-integration.mdx`, I would run:
+```
+git log --follow "**/vmware-vsphere-monitoring-integration.mdx"
+```
+## Docs site history before October 2021 [#archived-version]
+
+We had a large site restructure in October 2021 which lost most of the file history for our docs. You can find an archived version of our site pre-rework in the [pre-IA-2021](https://github.com/newrelic/docs-website/tree/pre-IA-2021) branch. By navigating the pre-rework version of our repo, you can find file history and more.
+
+## How to find deleted files [#deleted-files]
+
+There are multiple ways to find deleted files. These are roughly ordered by complexity:
+
+<CollapserGroup>
+  <Collapser
+    className="freq-link"
+    id="pr"
+    title="Finding the deletion PR"
+  >
+
+The easiest way to find a deleted file is to find the pull request that deleted it. There are multiple ways to accomplish this; here are some ideas:
+
+1. Use GitHub's search feature to search for relevany keywords. You can filter search results to only include PRs.
+2. If you have a rough idea of when the doc was deleted, you could try finding the pull request in the pull request tab. This list has thousands of PRs, so this may take some time.
+3. Lots of docs are deleted because of a Jira ticket. Search Jira for the ticket, where you will find the rough time the doc was deleted and hopefully a link to the PR itself.
+4. Ask in #doc_talk!
+
+  </Collapser>
+  <Collapser
+    className="freq-link"
+    id="releases"
+    title="Search through release PRs"
+  >
+
+By searching through release PRs, you can eventually find a branch created before the doc was deleted. You can find a list of release PRs in the [GitHub PR tab](https://github.com/newrelic/docs-we.bsite/pulls?q=is%3Apr+release+is%3Aclosed).
+
+A few tips:
+- Search by intervals of a month first. Once you find a branch that contains the doc, you can scope down to a week and then to a day. By decreasing the scope, you will eventually find the deleted doc in it's exact state before deletion.
+- To access the branch a PR comes from, go to that pull request's page and click on the branch name underneath the title and PR number.
+
+  </Collapser>
+
+  </Collapser>
+<Collapser
+    className="freq-link"
+    id="git-log"
+    title="Use git log"
+  >
+
+The most powerful and realiable way to find deleted files is to use git log. See [stackoverflow](https://stackoverflow.com/questions/7203515/how-to-find-a-deleted-file-in-the-project-commit-history/7203551#7203551) for more details.
+
+  </Collapser>
+</CollapserGroup>
diff --git a/src/content/docs/style-guide/writing-docs/writer-workflow/github-intro.mdx b/src/content/docs/style-guide/writing-docs/writer-workflow/github-intro.mdx
@@ -168,39 +168,3 @@ Every pull request needs these labels so we can see where our contributions come
   - `from_external`: A user opened it in the repo OR it came in through #customer-feedback process.
   - `from_tw`: One of us created it (unless we were passing along #customer-feedback). If the PR fixes an external issue, label it as `from_tw` since the work was done by a tech writer.
 
-## Check the edit history of a doc or file [#doc-history]
-Use any of these options to check or "diff" the history of a file.
-
-**Option 1: GitHub history tab**
-1. Navigate to the doc on the doc site and click **Edit page** in the right nav.
-2. Click **History** in the top right corner of the doc. 
-
-**Option 2: githistory.xy**
-1. Navigate to your specific file on GitHub.com:
-  ```
-  https://github.com/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx
-  ```
-2. In the url, replace `github.com` with `github.githistory.xyz`:
-  ```
-  https://github.githistory.xyz/newrelic/docs-website/blob/develop/src/content/docs/browser/new-relic-browser/browser-agent-spa-api/add-page-action.mdx
-  ```
-
-3. It will take you to a site which presents the visual history of that specific file. You can view changes by clicking through the commit history at the top of your page.
-
-**Option 3: Git blame**
-
-Follow [GitHub's documentation](https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file).
-
-Alternatively, you can use the following command in your terminal:
-```
-git log --follow "**/file_name_here.mdx"
-```
-This will output the commit history of that file. By default, it only shows the first few commits. You can scroll by pressing Return multiple times.
-
-For example, to find the commit history for  `vmware-vsphere-monitoring-integration.mdx`, I would run:
-```
-git log --follow "**/vmware-vsphere-monitoring-integration.mdx"
-```
-## Docs site history before October 2021 [#archived-version]
-
-We had a large site restructure in October 2021 which lost most of the file history for our docs. You can find an archived version of our site pre-rework in the [pre-IA-2021](https://github.com/newrelic/docs-website/tree/pre-IA-2021) branch. By navigating the pre-rework version of our repo, you can find file history and more.
diff --git a/src/nav/style-guide.yml b/src/nav/style-guide.yml
@@ -100,6 +100,8 @@ pages:
               path: /docs/style-guide/writing-docs/writer-workflow/peer-editor-workflow
             - title: GitHub troubleshooting
               path: /docs/style-guide/writing-docs/writer-workflow/github-troubleshooting
+            - title: Doc history and deleted docs
+              path: /docs/style-guide/writing-docs/writer-workflow/github-history
         - title: Article templates
           path: /docs/style-guide/writing-docs/article-templates
           pages: