docs: improve

docs/ABOUT.md

@@ -1,24 +1,25 @@
 # About
 
-Zig is a general-purpose programming language equipped with well-rounded toolchains that aims to be simple and familiar, yet disparate from what programmers rely on today.
-Its main attributes involve helping programmers to develop **robust**, **optimal**, and **reusable** software.
-All the while, Zig aims to remedy the design problems of older languages with features that promote safety through the use of [optionals][optionals], a unique take on [error handling][error-handling], and [compile-time execution][compile-time].
+Zig is a general-purpose programming language and toolchain, which aims to help produce **robust**, **optimal**, and **reusable** software.
 
-From the ground up, Zig was designed to be competitive with other systems programming languages and not be reliant on them.
-With bold claims such as, "Zig is faster than C" featured on its home page, being independent from other languages is a major design philosophy that it champions.
+It does this by striving for simplicity: there's no hidden control flow, no hidden memory allocations, and no macros.
+However, there's still a modern design: a powerful type system with sum types and [optionals][optionals], explicit [error handling][error-handling], and [compile-time execution][compile-time].
 
-Zig has a lot of faculties that really makes it double down on its notion of independence.
-The standard library that Zig provides harbors many common functions that perform fast to ensure that a reliance on FFI and external libraries is not essential.
-Zig also provides a well-rounded [build system][build-system] so that Zig is not dependent on alternative build tools, such as make, cmake, or ninja.
+Zig tries to be a DSL for emitting optimal machine code.
 
-The home page for Zig is [ziglang.org][ziglang.org].
-Zig provides a complete summary of the language's current features, grammars, and philosophies at [ziglang.org/documentation/master/][ziglang.org/docs].
-It's highly recommended that newcomers use a mix of the documentation and other [community resources][zig-community] to learn Zig in a well-rounded fashion.
+For more information, see [ziglang.org][ziglang.org].
+
+//Zig provides a complete summary of the language's current features, grammar, and philosophy in the [Zig Language Reference][langref].
+//It's highly recommended that newcomers use a mix of the documentation and other [community resources][zig-community] to learn Zig in a well-rounded fashion.
+
+// Compatibility with C is as good as it gets: Zig ships with C compiler toolchains, so you can just import a C header file and call functions.
+// Zig also provides a [build system][build-system] so that Zig isn't dependent on alternative build tools, such as make, cmake, or ninja.
+// And Zig is excellent at cross compilation.
 
 [build-system]: https://ziglang.org/learn/overview/#zig-build-system
 [compile-time]: https://ziglang.org/learn/overview/#compile-time-reflection-and-compile-time-code-execution
 [error-handling]: https://ziglang.org/learn/overview/#a-fresh-take-on-error-handling
+[langref]: https://ziglang.org/documentation/0.12.0/
 [optionals]: https://ziglang.org/learn/overview/#optional-type-instead-of-null-pointers
 [ziglang.org]: https://ziglang.org/
-[ziglang.org/docs]: https://ziglang.org/documentation/master/
 [zig-community]: https://github.com/ziglang/zig/wiki/Community

docs/INSTALLATION.md

@@ -1,51 +1,42 @@
 # Installation
 
-There are many ways to install Zig, and the number of ways to install Zig are steadily increasing as the language matures.
-Fortunately, all of the popular installation methods are listed on the [Zig install page][install-zig].
+You can download Zig from the [Releases][zig-download] page, or [using a package manager][package-manager].
 
-## Zig version
+## Supported Zig version
 
 Exercism currently supports Zig 0.12.0 (released on 2024-04-20) only.
 
 An exercise may be compatible with a different Zig version, but that isn't guaranteed.
-Zig has not yet reached version 1.0, and breaking changes are common.
+Zig hasn't yet reached version 1.0, and breaking changes are common.
 
-## Additional utilities
+## The Zig Language Server - comprehensive editor support for Zig
 
-### Zig fmt - Generating well-formatted code
+This third-party software provides editor completions and enhanced Zig code navigation features, which can help you learn the language faster.
 
-When completing any exercise, you may use all kinds of code styles for your solutions.
-However, outside of solving exercises, such as making applications or libraries, it's typically a good idea to make your code consistent and readable.
-Those assumption are especially important when others who would want to help out with your projects would have to read your code.
+You can install ZLS [here][zls-install].
 
-To fix this problem the Zig compiler comes with a built-in lightweight [linter][linters] to format your code in a convenient manner.
-This code formatter aims to follow the [style guide][style-guide] already established by the [Zig documentation][documentation].
+## Other commands
 
-To see the features of Zig's native formatter use the following command:
+### `zig fmt`
+
+The Zig executable contains a code formatter.
+To format `file.zig`, run:
 
 ```bash
-zig fmt --help
+zig fmt file.zig
 ```
 
-### Zig Zen - Rules to code by
+For more details on the suggested code style, see the [Zig Style Guide][style-guide].
 
-Sometimes some direction goes a long way when completing any task, even when writing code.
-Thankfully we have a fun command built right into the Zig compiler to remind ourselves of some of the goals that go into writing good Zig code.
+### `zig zen`
 
-To check out these words of wisdom you can use the following command:
+The Zig executable has a command to remind us of Zig's design goals:
 
 ```bash
 zig zen
 ```
 
-### The Zig Language Server - Comprehensive editor support for Zig
-
-This third-party software provides editor completions and enhanced Zig code navigation features which can help you learn the language faster.
-
-You can install ZLS [here][install-zls].
-
-[documentation]: https://ziglang.org/documentation/master/
-[install-zig]: https://ziglang.org/download/
-[linters]: https://en.wikipedia.org/wiki/Lint_(software)
-[style-guide]: https://ziglang.org/documentation/master/#Style-Guide
-[install-zls]: https://install.zigtools.org/
+[package-manager]: https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager
+[style-guide]: https://ziglang.org/documentation/0.12.0/#Style-Guide
+[zig-download]: https://ziglang.org/download/
+[zls-install]: https://install.zigtools.org/

docs/LEARNING.md

@@ -1,15 +1,15 @@
 # Learning
 
-- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it.
-- [Awesome Zig][awesome-zig] is a good collection of Zig projects made by various people.
-  The collection features projects involving well developed Zig code.
-- [Zighelp][zighelp] is an excellent primer that explains the language features that Zig has to offer.
-- [Ziglings][ziglings] is highly recommended.
-  Learn Zig by fixing tiny broken programs.
+- [Ziglings][ziglings] is a highly recommended introduction to Zig, which asks you to fix tiny broken programs.
+- [zig.guide][zig-guide] is another great introduction to Zig.
+- [The Zig Language Reference][langref] is the main reference documentation.
+- [Learning Zig][learning-zig] is another great introduction to Zig.
+- [Awesome Zig][awesome-zig] is a collection of Zig projects.
 - [Zig SHOWTIME][zig-showtime] is a livestreamed show where members of the Zig community share code and ideas.
 
 [awesome-zig]: https://github.com/catdevnull/awesome-zig
-[documentation]: https://ziglang.org/documentation/master/
-[zighelp]: https://zighelp.org/
+[langref]: https://ziglang.org/documentation/0.12.0/
+[learning-zig]: https://www.openmymind.net/learning_zig/
 [zig-showtime]: https://zig.show/
+[zig-guide]: https://zig.guide/
 [ziglings]: https://github.com/ratfactor/ziglings

docs/RESOURCES.md

@@ -1,21 +1,24 @@
 # Resources
 
-- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it.
-- [The Zig Standard Library][std] is a good reference to learn how Zig code is written and shows many of the functions that you could import into your own code.
-- [Awesome Zig][awesome-zig] is a curated list of Zig projects.
+- [The Zig Language Reference][langref] is the main reference documentation.
+- [The Zig Standard Library][std] is one of the best places to read good Zig code.
+- [The Zig Programming Language Discord][discord-zig] is the main Zig [Discord][discord].
+  It provides a great way to get in touch with the Zig community, and get some quick, direct help for any Zig-related problem.
 - [#zig][irc] on irc.freenode.net is the main Zig IRC channel.
-- [Stack Overflow][stack-overflow] can be used to discover code snippets and solutions to problems that may have already asked and maybe solved by others.
-- [/r/Zig][reddit] is the main Zig subreddit.
-- [The Zig Programming Language Discord][discord-zig] is the main [Discord][discord].
-  It provides a great way to get in touch with the Zig community at large, and get some quick, direct help for any Zig related problem.
+- [Awesome Zig][awesome-zig] is a curated list of Zig projects.
 - [The Zig SHOWTIME Newsletter][newsletter] announces new episodes, important events, and links to interesting new Zig projects.
+- [Ziggit][ziggit] is the main Zig forum.
+- [/r/Zig][reddit] is the main Zig subreddit.
+
+For a longer list of community spaces, see the [Community wiki page][community].
 
 [awesome-zig]: https://github.com/catdevnull/awesome-zig
+[community]: https://github.com/ziglang/zig/wiki/Community
 [discord]: https://discordapp.com
 [discord-zig]: https://discord.com/invite/gxsFFjE
-[documentation]: https://ziglang.org/documentation/master
 [irc]: https://webchat.freenode.net/?channels=%23zig
+[langref]: https://ziglang.org/documentation/0.12.0/
 [newsletter]: https://zig.show/
 [reddit]: https://www.reddit.com/r/Zig
-[stack-overflow]: https://stackoverflow.com/questions/tagged/zig
-[std]: https://github.com/ziglang/zig/tree/master/lib/std
+[std]: https://github.com/ziglang/zig/tree/0.12.0/lib/std
+[ziggit]: https://ziggit.dev/

docs/TESTS.md

@@ -1,31 +1,26 @@
-# Writing the Code
+# Writing your solution
 
-Write your code in `<exercise_name>.zig`.
-Some exercises come with prewritten signatures for specific Zig constructs, such as [constants][constants], [functions][functions], [imports][imports], [structs][structs], and [potentially many more][et-cetera]!
+Write your solution in `<exercise_name>.zig`.
+Exercism provides a solution skeleton there for each exercise.
 
-These prewritten signatures are meant to help you towards completing exercises by providing a clear starting point.
-However, starting from these signatures is not necessary.
-Especially when any written code which passes their tests are perfectly acceptable solutions.
+We intend each skeleton to provide a clear starting point, but you don't need to use everything from it.
+In general, any solution that passes every test is valid.
 
-## Running Tests
+However, we recommend continuing after you've got the tests to pass.
+Try to refactor, and turn your solution into beautiful idiomatic Zig!
 
-To run the tests, all you need to do is run the following command:
+## Running the tests
+
+To test your solution, run the below command in the exercise's root directory:
 
 ```bash
 zig test test_exercise_name.zig
 ```
 
 replacing `exercise_name` with the name of the exercise.
-The command above has to be run in the exercise's root directory since its test file should be in the same spot.
-Additionally, all of the tests for any given exercise are enabled by default, and none of the tests are skippable.
-
-Since all tests have these stipulations, you would have to [comment out][comments] tests that are not passing if you wish to go through each test one by one.
-Commenting out a test is as simple as starting each line with a `//`.
-Otherwise, when you're confident that your solution can pass the tests, you can un-comment those tests to see if it passes.
-
-[constants]: https://ziglang.org/documentation/master/#Assignment
-[comments]: https://ziglang.org/documentation/master/#Comments
-[functions]: https://ziglang.org/documentation/master/#Functions
-[et-cetera]: https://ziglang.org/documentation/master/
-[imports]: https://ziglang.org/documentation/master/#import
-[structs]: https://ziglang.org/documentation/master/#struct
+
+By default, the test file enables every test.
+That is, no test is currently skipped by default.
+To go through tests one at a time, you can [comment out][comments] tests by adding `//` to the start of a line
+
+[comments]: https://ziglang.org/documentation/0.12.0/#Comments

exercises/practice/anagram/.docs/instructions.append.md

@@ -10,9 +10,9 @@ The `BufSet` does that itself.
 For more details on hash maps in Zig, see:
 
 - [Hexops - Zig hashmaps explained][zig-hashmaps-explained]
-- [Zighelp - Hash Maps][zighelp]
+- [zig.guide - Hash Maps][zig-guide-hashmaps]
 - [Zig Standard Library - `buf_set.zig`][buf-set]
 
 [buf-set]: https://github.com/ziglang/zig/blob/0.12.0/lib/std/buf_set.zig
 [zig-hashmaps-explained]: https://devlog.hexops.com/2022/zig-hashmaps-explained/
-[zighelp]: https://zighelp.org/chapter-2/#hash-maps
+[zig-guide-hashmaps]: https://zig.guide/standard-library/hashmaps

exercises/practice/collatz-conjecture/.docs/instructions.append.md

@@ -13,8 +13,8 @@ For more details about errors in Zig, see:
 
 - [Learning Zig - Errors][learning-zig-errors]
 - [Ziglings - Exercise 21][ziglings-exercise-21]
-- [Zighelp - Errors][zighelp-errors]
+- [zig.guide - Errors][zig-guide-errors]
 
 [learning-zig-errors]: https://www.openmymind.net/learning_zig/language_overview_2/#errors
-[zighelp-errors]: https://zighelp.org/chapter-1/#errors
+[zig-guide-errors]: https://zig.guide/language-basics/errors
 [ziglings-exercise-21]: https://codeberg.org/ziglings/exercises/src/commit/0d46acfa02d0c29fdfb3651e82a77284dd8f2e00/exercises/021_errors.zig

exercises/shared/.docs/help.md

@@ -1,20 +1,21 @@
 # Help
 
-- [The Zig Programming Language Documentation][documentation] is a great overview of all of the language features that Zig provides to those who use it.
-- [Zig Learn][zig-learn] is an excellent primer that explains the language features that Zig has to offer.
-- [Ziglings][ziglings] is highly recommended.
-  Learn Zig by fixing tiny broken programs.
-- [The Zig Programming Language Discord][discord-zig] is the main [Discord][discord].
-  It provides a great way to get in touch with the Zig community at large, and get some quick, direct help for any Zig related problem.
+- [The Zig Programming Language Discord][discord-zig] is the main Zig [Discord][discord].
+  It provides a great way to get in touch with the Zig community, and get some quick, direct help for any Zig-related problem.
 - [#zig][irc] on irc.freenode.net is the main Zig IRC channel.
-- [/r/Zig][reddit] is the main Zig subreddit.
-- [Stack Overflow][stack-overflow] can be used to discover code snippets and solutions to problems that may have already asked and maybe solved by others.
+- [Ziggit][ziggit] is the main Zig forum.
+- [/r/Zig][sureddit] is the main Zig subreddit.
+- [Ziglings][ziglings] is a highly recommended introduction to Zig, which asks you to fix tiny broken programs.
+- [zig.guide][zig-guide] is a great introduction to Zig.
+- [Learning Zig][learning-zig] is another great introduction to Zig.
+- [The Zig Language Reference][langref] is the main reference documentation.
 
 [discord]: https://discordapp.com
 [discord-zig]: https://discord.com/invite/gxsFFjE
-[documentation]: https://ziglang.org/documentation/master
 [irc]: https://webchat.freenode.net/?channels=%23zig
-[reddit]: https://www.reddit.com/r/Zig
-[stack-overflow]: https://stackoverflow.com/questions/tagged/zig
-[zig-learn]: https://ziglearn.org/
+[langref]: https://ziglang.org/documentation/0.12.0/
+[learning-zig]: https://www.openmymind.net/learning_zig/
+[sureddit]: https://www.reddit.com/r/Zig
+[ziggit]: https://ziggit.dev/
+[zig-guide]: https://zig.guide/
 [ziglings]: https://github.com/ratfactor/ziglings