Merge branch 'develop' into spencer-oppia#4397

XichengSpencer · May 16, 2023 · a856e6e · a856e6e
2 parents a433a75 + 832f9ce
commit a856e6e
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 30 deletions.
diff --git a/wiki/Debugging-Docs.md b/wiki/Debugging-Docs.md
@@ -0,0 +1,50 @@
+Whenever you are debugging a problem, you may find it useful to keep a record of your debugging process. We often do this already in issues. Issues usually begin with a detailed description of the problem, which is followed by discussion, reports of attempted debugging steps, and what root cause was identified. However, issues' linear comment structure makes them more amenable to communication among team members than organizing your thoughts. Debugging docs, on the other hand, serve primarily to organize your thoughts.
+
+**Note:** In general, we strongly recommend writing and sharing a debugging doc if you can't figure out a solution to a problem within the **first 2 hours** of working on it.
+
+## Table of Contents
+
+- [Benefits](#benefits)
+- [How to Write a Debugging Doc](#how-to-write-a-debugging-doc)
+  - [1. Begin with Describing What Goes Wrong](#1-begin-with-describing-what-goes-wrong)
+  - [2. Describe Your Investigations](#2-describe-your-investigations)
+  - [3. Document Your Guesses and Testing](#3-document-your-guesses-and-testing)
+  - [4. Continue/Review from Mentor](#4-continuereview-from-mentor)
+  - [5. Document Your Solution](#5-document-your-solution)
+- [Get Started](#get-started)
+
+## Benefits
+
+Primarily, debugging docs help keep your thoughts organized. When you have written down the steps you've already tried and the results of your investigations, you don't have to worry about forgetting your earlier work. Further, when you document your work, you force yourself to reflect on what you've already tried. Debugging docs also make it easy for you to bring someone else up to speed on your bug.
+
+Finally, these documents can serve as records of debugging strategies and bug causes that we can reference later on. For example, we might search these debugging docs for an error message we are encountering to see if it has been fixed before.
+
+## How to Write a Debugging Doc
+
+### 1. Begin with Describing What Goes Wrong
+
+Your description should include:
+
+- Context: What branch or PR is the bug happening on? If this is happening locally, what system are you running, and what code changes have you made?
+
+- How the Bug Manifests: This might include error logs that you pasted into the document, screenshots, or links to a test run on a PR. **If you provide a link, copy the relevant part of the page you are linking to.** This keeps the document self-contained so we can search them. It also makes the doc easier for people to read.
+
+### 2. Describe Your Investigations
+
+What did you try, and what happened when you tried it? You want to include enough detail so that someone could reproduce your investigation to see if they get the same results.
+
+### 3. Document Your Guesses and Testing
+
+After some investigation, you might have some ideas for what might be going wrong. Document your guesses and describe how you go about testing them. Report the results of that testing and describe whether you think your guess was right. What's your reasoning?
+
+### 4. Continue/Review from Mentor
+
+Keep going! Continue documenting your investigations, guesses, and tests of those guesses. You can share your debugging doc with your assigned onboarding mentor to review and help you in finding the root cause of the issue or the solution.
+
+### 5. Document Your Solution
+
+Once you figure out what the problem was, write that down too! Include an analysis of how the root cause you identify caused the errors you described at the top. Often, this will take the form of one of your suspected solutions.
+
+## Get Started
+
+Ready to get started with your own debugging doc? You can make a copy of [this template](https://docs.google.com/document/d/1OBAio60bchrNCpIrPBY2ResjeR11ekcN0w5kNJ0DHw8) to get started.
diff --git a/wiki/Debugging.md b/wiki/Debugging.md
@@ -9,4 +9,4 @@ Generally, finding the root cause of a bug is a question of strategically checki
 3. Based on the environment you've identified in steps 1 + 2, write a test case which the bug causes to fail (if one doesn't already exist). This gives you an automatic way to check whether or not the bug is fixed.
 4. Then, work towards the solution, until the test case you wrote in step 3 passes.
 
-Unless the bug you are trying to fix is trivial, we strongly recommend creating a debugging doc to organize your work. You can use this debugging doc to write down any pertinent information about the issue and to organize your debugging process, and it will make it much easier to ask for help from others since all the necessary information is there. You can find more guidance [here](https://github.com/oppia/oppia-android/wiki/Get-Help#before-you-ask-a-general-question) on how to write a debugging doc.
+Unless the bug you are trying to fix is trivial, we recommend creating a debugging doc to organize your work and easily communicate it to other team members. See [Debugging Docs](https://github.com/oppia/oppia-android/wiki/Debugging-Docs) for guidance on how to write a debugging doc.
diff --git a/wiki/Frequent-Errors-and-Solutions.md b/wiki/Frequent-Errors-and-Solutions.md
@@ -30,29 +30,4 @@ To solve this
 If there is an error with any of the lint failures it will be detailed in the command line itself. 
 
 ## Facing error while debugging code
-Whenever you are debugging a problem, you may find it useful to keep a record of your debugging process. We often do this already in issues. Issues usually begin with a detailed description of the problem, which is followed by discussion, reports of attempted debugging steps, and what root cause was identified. However, issues' linear comment structure makes them more amenable to communication among team members than organizing your thoughts. Debugging docs, on the other hand, serve primarily to organize your thoughts.
-
-### Benefits
-Primarily, debugging docs help keep your thoughts organized. When you have written down the steps you've already tried and the results of your investigations, you don't have to worry about forgetting your earlier work. Further, when you document your work, you force yourself to reflect on what you've already tried. Debugging docs also make it easy for you to bring someone else up to speed on your bug. 
-
-### How to Write a Debugging Doc
-
-#### 1. Begin with Describing What Goes Wrong
-Your description should include:
- - Context: What branch or PR is the bug happening on? If this is happening locally, what system are you running, and what code changes have you made?
- - How the Bug Manifests: This might include error logs that you pasted into the document, screenshots, or links to a test run on a PR. If you provide a link, copy the relevant part of the page you are linking to. This keeps the document self-contained so we can search them. It also makes the doc easier for people to read.
-
-#### 2. Describe Your Investigations
-What did you try, and what happened when you tried it? You want to include enough detail so that someone could reproduce your investigation to see if they get the same results.
-
-#### 3. Document Your Guesses and Testing
-After some investigation, you might have some ideas for what might be going wrong. Document your guesses and describe how you go about testing them. Report the results of that testing and describe whether you think your guess was right. What's your reasoning?
-
-#### 4. Continue/Review from Mentor
-Keep going! Continue documenting your investigations, guesses, and tests of those guesses. You can share your debugging doc with your assigned onboarding mentor to review and help you in finding the root cause of the issue or the solution. 
-
-#### 5. Document Your Solution
-Once you figure out what the problem was, write that down too! Include an analysis of how the root cause you identify caused the errors you described at the top. Often, this will take the form of one of your suspected solutions.
-
-#### Get Started
-Ready to get started with your own debugging doc? You can make a copy of [this template](https://docs.google.com/document/d/1OBAio60bchrNCpIrPBY2ResjeR11ekcN0w5kNJ0DHw8/edit?usp=sharing) to get started. 
+If you are running into an error that you cannot debug, follow the guidelines outlined on this [wiki page](https://github.com/oppia/oppia-android/wiki/Debugging).
diff --git a/wiki/Get-Help.md b/wiki/Get-Help.md
@@ -100,9 +100,9 @@ paste a screenshot
 
 ### Before you ask a general question
 
-* We expect that you have already **set up Oppia on your machine**, and it is successfully running. (If not, kindly do that first!)
-* Prepare a debugging doc following [this template](https://docs.google.com/document/d/1OBAio60bchrNCpIrPBY2ResjeR11ekcN0w5kNJ0DHw8). For more information on how to prepare a debugging doc, follow the guidelines provided on [this wiki page](https://github.com/oppia/oppia-android/wiki/Frequent-Errors-and-Solutions#how-to-write-a-debugging-doc).
-* If there are **checks** on your PR, and you haven’t done any changes in that direction, kindly understand that sometimes they just fail due to flakiness. You should request for a re-run of those only when it’s preventing your PR from getting merged.
+- We expect that you have already **set up Oppia on your machine**, and it is successfully running. (If not, kindly do that first!)
+- The guidelines provided on the [Debugging Docs wiki page](https://github.com/oppia/oppia-android/wiki/Debugging-Docs).
+- If there are **failing checks** on your PR, and you haven't done any changes that might cause them, kindly understand that sometimes they just fail due to flakiness. You should request for a re-run of those only when it’s preventing your PR from getting merged.
 
 ### How to ask a general question
 

diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
@@ -37,6 +37,7 @@
     * [Accessibility Guide](https://github.com/oppia/oppia-android/wiki/Accessibility-A11y-Guide)
     * [Debugging](https://github.com/oppia/oppia-android/wiki/Debugging)
       * [How do I find the root cause of a bug?](https://github.com/oppia/oppia-android/wiki/Debugging#How-do-I-find-the-root-cause-of-a-bug)
+      * [Debugging Docs](https://github.com/oppia/oppia-android/wiki/Debugging-Docs)
   * [Background Processing](https://github.com/oppia/oppia-android/wiki/Background-Processing)
     * [Kotlin Coroutines](https://github.com/oppia/oppia-android/wiki/Kotlin-Coroutines)
     * [DataProvider & LiveData](https://github.com/oppia/oppia-android/wiki/DataProvider-&-LiveData)