Merge branch 'tr/docs_best_practice'

docs/docs/core-abilities/auto_best_practices.md

@@ -3,18 +3,21 @@
 
 ## Overview
 
+![Auto best practice suggestion graph](https://www.qodo.ai/images/pr_agent/auto_best_practices_graph.png){width=684}
+
+
 ### Finding Code Problems - Exploration Phase
 
-Qodo Merge `improve` tool identifies potential issues, problems and bugs in Pull Request (PR) code changes. 
-Rather than focusing on generic concepts like code style, the tool intelligently analyzes code to detect meaningful problems. 
+The `improve` tool identifies potential issues, problems and bugs in Pull Request (PR) code changes. 
+Rather than focusing on minor issues like code style or formatting, the tool intelligently analyzes code to detect meaningful problems. 
 
-The analysis is intentionally broad to allow identifying a wide range of potential issues.
-This open-ended _exploration_ enables the tool to surface any relevant issues without being constrained to predefined categories.
+The analysis intentionally takes a flexible, _exploratory_ approach to identify meaningful potential issues, allowing the tool to surface relevant code suggestions without being constrained by predefined categories.
 
 ### Tracking Implemented Suggestions
 
 Qodo Merge features a novel [tracking system](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking) that automatically detects when PR authors implement AI-generated code suggestions. 
-All accepted suggestions are aggregated in a repository-specific wiki page called [`.pr_agent_accepted_suggestions`](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_accepted_suggestions).
+All accepted suggestions are aggregated in a repository-specific wiki page called [`.pr_agent_accepted_suggestions`](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_accepted_suggestions)
+(Why Wiki - see [here](https://qodo-merge-docs.qodo.ai/usage-guide/enabling_a_wiki/#why-wiki)).
 
 ### Learning and Applying Auto Best Practices
 
@@ -29,22 +32,23 @@ This creates a two-phase analysis:
 
 By keeping these phases decoupled, the tool remains free to discover new or unseen issues and problems, while also learning from past experiences.
 
-When presenting the suggestions generated by the `improve` tool, Qodo Merge will add a dedicated label for each suggestion generated from the auto best practices - 'Learned Best Practice':
 
-![Auto best practice suggestion](https://www.qodo.ai/images/pr_agent/auto_best_practices.png){width=512}
+When presenting the suggestions generated by the `improve` tool, Qodo Merge will add a dedicated label for each suggestion generated from the auto best practices - 'Learned best practice':
+
+![Auto best practice suggestion](https://www.qodo.ai/images/pr_agent/auto_best_practices.png){width=684}
 
 
 ## Auto Best Practices vs Custom Best Practices
 
-Teams and companies can also manually define their own [custom best practices](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) in Qodo Merge to evaluate PR code changes. 
+Teams and companies can also manually define their own [custom best practices](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) in Qodo Merge. 
 
-When custom best practices exist, Qodo Merge will still generate an 'auto best practices' wiki file, though it won't use it in the `improve` tool analysis. 
+When custom best practices exist, Qodo Merge will still generate an 'auto best practices' wiki file, though it won't be used by the `improve` tool. 
 However, this auto-generated file can still serve two valuable purposes:
 
 1. It can help enhance your custom best practices with additional insights derived from suggestions your team found valuable enough to implement
 2. It demonstrates effective patterns for writing AI-friendly best practices
 
-We recommend regularly reviewing the auto best practices file to refine your custom rules, even when using custom best practices.
+Even when using custom best practices, we recommend regularly reviewing the auto best practices file to refine your custom rules.
 
 ## Relevant configurations
 

docs/docs/usage-guide/enabling_a_wiki.md

@@ -3,12 +3,12 @@
 
 For optimal functionality of Qodo Merge, we recommend enabling a wiki for each repository where Qodo Merge is installed. The wiki serves several important purposes:
 
-**Key Wiki Features:**
+**Key Wiki Features: 💎**
 
 - Storing a [configuration file](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#wiki-configuration-file)
 - Defining a [`best_practices.md`](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) file
 - Track [accepted suggestions](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking)
-- Facilitates learning over time by creating an [auto_best_practices.md]() file
+- Facilitates learning over time by creating an [auto_best_practices.md](https://qodo-merge-docs.qodo.ai/core-abilities/auto_best_practices) file
 
 
 **Setup Instructions (GitHub):**
@@ -21,4 +21,13 @@ To enable a wiki for your repository:
 4. Enable the "Wikis" option by checking the corresponding box
 5. Return to your repository's main page
 6. Look for the newly added "Wiki" tab in the top navigation
-7. Initialize your wiki by clicking "Create the first page" (this step is important - without creating an initial page, the wiki will not be fully functional)
+7. Initialize your wiki by clicking "Create the first page" and saving (this step is important - without creating an initial page, the wiki will not be fully functional)
+
+### Why Wiki?
+
+- Your code (and its derivatives, including accepted code suggestions) is yours. Qodo Merge will never store it on external servers.
+- Repository changes typically require pull requests, which create overhead and are time-consuming. This process is too cumbersome for auto data aggregation, and is not very convenient even for managing frequently updated content like configuration files and best practices.
+- A repository wiki page provides an ideal balance:
+    - It lives within your repository, making it suitable for code-related documentation
+    - It enables quick updates without the overhead of pull requests
+    - It maintains full Git version control, allowing you to track changes over time.