Link to best practices more

exercism · Aug 16, 2024 · 50bf91b · 50bf91b
1 parent 9ab126b
commit 50bf91b
Show file tree

Hide file tree

Showing 9 changed files with 27 additions and 10 deletions.
diff --git a/building/tooling/analyzers/README.md b/building/tooling/analyzers/README.md
@@ -18,7 +18,7 @@ You can use the following documents to learn more about building an analyzer:
 - [Creating a Analyzer from scratch](/docs/building/tooling/analyzers/creating-from-scratch)
 - [The Analyzer interface.](/docs/building/tooling/analyzers/interface)
 - [How to build a Docker image with Docker for local testing and deployment](/docs/building/tooling/analyzers/docker)
+- [Best practices](/docs/building/tooling/best-practices)
 - [Writing Analyzer comments](/docs/building/tooling/analyzers/comments)
 - [Tagging solutions](/docs/building/tooling/analyzers/tags)
 - [Guidance for building an Analyzer](/docs/building/tooling/analyzers/guidance)
-- [Best practices](/docs/building/tooling/best-practices)
diff --git a/building/tooling/analyzers/creating-from-scratch.md b/building/tooling/analyzers/creating-from-scratch.md
@@ -7,9 +7,10 @@ These are the steps to get going:
 1. Check [our repository list for an existing `...-analyzer`](https://github.com/search?q=org%3Aexercism+analyzer&type=repositories) to ensure that one doesn't already exist.
 2. Scan the [contents of this directory](/docs/building/tooling/analyzers) to ensure you are comfortable with the idea of creating an Analyzer.
 3. Start a new topic on [the Exercism forum][building-exercism] telling us which language you'd like to create an Analyzer for.
-4. Once an Analyzer repo has been created, use [the Analyzer interface document](/docs/building/tooling/analyzers/interface) to help guide your implementation.
+4. Once an Analyzer repo has been created for you, use [the Analyzer interface](/docs/building/tooling/analyzers/interface) and [Best practices](/docs/building/tooling/best-practices) documents to help guide your implementation.
 
-We have an incredibly friendly and supportive community who will be happy to help you as you work through this! If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
+We have an incredibly friendly and supportive community who will be happy to help you as you work through this!
+If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
 
 [building-exercism]: https://forum.exercism.org/c/exercism/building-exercism/125
 [exercism-repo]: https://github.com/exercism/exercism
diff --git a/building/tooling/analyzers/interface.md b/building/tooling/analyzers/interface.md
@@ -17,6 +17,10 @@ All interactions with the Exercism website are handled automatically. Analyzers
 The analyzer gets 100% machine resources for a 20 second window per solution.
 After 20 seconds, the process is halted and reports a time-out.
 
+```exercism/note
+We highly recommend following our [Performance Best Practices document](/docs/building/tooling/best-practices#h-performance) to reduce the chance of timeouts.
+```
+
 ## Output format
 
 ### analysis.json

diff --git a/building/tooling/docker.md b/building/tooling/docker.md
@@ -15,7 +15,7 @@ Our [Best Practices page](/docs/building/tooling/best-practices) has lots of tip
 The test runner gets 100% CPU with 3GB of memory for a 20 second window per solution.
 After 20 seconds, the process is halted and reports a time-out with a 408 error code.
 
-We highly recommend following our [Performance Best Practices document](/docs/building/tooling/best-practices#h-performance) to reduce the chance of timeout occuring.
+We highly recommend following our [Performance Best Practices document](/docs/building/tooling/best-practices#h-performance) to reduce the chance of timeouts.
 
 ### Stdout/stderr
 

diff --git a/building/tooling/representers/README.md b/building/tooling/representers/README.md
@@ -33,6 +33,6 @@ You can use the following documents to learn more about building a representer:
 
 - [Creating a Representer from scratch](/docs/building/tooling/representers/creating-from-scratch)
 - [The Representer interface](/docs/building/tooling/representers/interface)
-- [How to normalize representations for the highest efficiency](/docs/building/tooling/representers/normalization)
 - [How to build a Docker image with Docker for local testing and deployment](/docs/building/tooling/representers/docker)
 - [Best practices](/docs/building/tooling/best-practices)
+- [How to normalize representations for the highest efficiency](/docs/building/tooling/representers/normalization)
diff --git a/building/tooling/representers/creating-from-scratch.md b/building/tooling/representers/creating-from-scratch.md
@@ -7,9 +7,10 @@ These are the steps to get going:
 1. Check [our repository list for an existing `...-representer`](https://github.com/search?q=org%3Aexercism+representer&type=repositories) to ensure that one doesn't already exist.
 2. Scan the [contents of this directory](/docs/building/tooling/representers) to ensure you are comfortable with the idea of creating an Representer.
 3. Start a new topic on [the Exercism forum][building-exercism] telling us which language you'd like to create a Representer for.
-4. Once a Representer repo has been created, use [the Representer interface document](/docs/building/tooling/representers/interface) to help guide your implementation.
+4. Once a Representer repo has been created for you, use [the Representer interface](/docs/building/tooling/representers/interface) and [Best practices](/docs/building/tooling/best-practices) documents to help guide your implementation.
 
-We have an incredibly friendly and supportive community who will be happy to help you as you work through this! If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
+We have an incredibly friendly and supportive community who will be happy to help you as you work through this!
+If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
 
 [building-exercism]: https://forum.exercism.org/c/exercism/building-exercism/125
 [exercism-repo]: https://github.com/exercism/exercism
diff --git a/building/tooling/representers/interface.md b/building/tooling/representers/interface.md
@@ -1,6 +1,8 @@
 # The Representer Interface
 
-All interactions with the Exercism website are handled automatically. Representers have the single responsibility of taking a solution and returning a representation of it. See the [introduction](/docs/building/tooling/representers#introduction) for more information.
+All interactions with the Exercism website are handled automatically.
+Representers have the single responsibility of taking a solution and returning a representation of it.
+See the [introduction](/docs/building/tooling/representers#introduction) for more information.
 
 ## Execution
 
@@ -18,6 +20,10 @@ All interactions with the Exercism website are handled automatically. Represente
 The representer gets 100% machine resources for a 20 second window per solution.
 After 20 seconds, the process is halted and reports a time-out.
 
+```exercism/note
+We highly recommend following our [Performance Best Practices document](/docs/building/tooling/best-practices#h-performance) to reduce the chance of timeouts.
+```
+
 ## Output format
 
 ### representation.txt

diff --git a/building/tooling/test-runners/creating-from-scratch.md b/building/tooling/test-runners/creating-from-scratch.md
@@ -7,9 +7,10 @@ These are the steps to get going:
 1. Check [our repository list for an existing `...-test-runner`](https://github.com/search?q=org%3Aexercism+test-runner&type=repositories) to ensure that one doesn't already exist.
 2. Scan the [contents of this directory](/docs/building/tooling/test-runners) to ensure you are comfortable with the idea of creating an Test Runner.
 3. Start a new topic on [the Exercism forum][building-exercism] telling us which language you'd like to create a Test Runner for.
-4. Once a Test Runner repo has been created, use [the Test Runner interface document](/docs/building/tooling/test-runners/interface) to help guide your implementation. There is a [generic test runner repository template](https://github.com/exercism/generic-test-runner/) that you can use to kick-start development.
+4. Once a Test Runner repo has been created for you, use [the Test Runner interface](/docs/building/tooling/test-runners/interface) and [Best practices](/docs/building/tooling/best-practices) documents to help guide your implementation.
 
-We have an incredibly friendly and supportive community who will be happy to help you as you work through this! If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
+We have an incredibly friendly and supportive community who will be happy to help you as you work through this!
+If you get stuck, please start a new topic on [the Exercism forum][building-exercism] or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
 
 [building-exercism]: https://forum.exercism.org/c/exercism/building-exercism/125
 [exercism-repo]: https://github.com/exercism/exercism
diff --git a/building/tooling/test-runners/interface.md b/building/tooling/test-runners/interface.md
@@ -18,6 +18,10 @@ All interactions with the Exercism website are handled automatically and are not
 The test runner gets 100% CPU with 3GB of memory for a 20 second window per solution.
 After 20 seconds, the process is halted and reports a time-out.
 
+```exercism/note
+We highly recommend following our [Performance Best Practices document](/docs/building/tooling/best-practices#h-performance) to reduce the chance of timeouts.
+```
+
 ## Output format
 
 The following fields are supported in `results.json` files: