The new documentation needs feedbacks

[kazk]

The project is in alpha stage and now available for testing on https://kazk.github.io/codewars.com/.

Any feedback is appreciated.
Note that styling hasn't been the priority and mostly incomplete. We're planning to work on this in July.
The source is kept under docs and will be open for contribution soon.

---

Experimental search feature is available on /search which uses lunr.js and supports some modifiers.
Experimental cookbook style documentation is added. See this example.
API documentation can be found on /api.

See docs for more information.

Updates

TODO

• Review and update old documentations about Codewars platform
• Update Test.assert(Not)ApproxEquals (JavaScript CW-2)
• Improve Test.randomNumber, Test.randomToken (JavaScript CW-2)
• Fix typo soltion.txt in "Restricting Solution" cookbook
• Use target="_blank" for external links

Proposals

• [Tutorial] Writing random tests
• [FAQ] Why are the tests failing even though I have printed the correct results to the console?

[DonaldKellett]

Glad to see that the new docs are now available for testing 😄 I currently see no problem with the layout (CSS); it all looks simple and neat and the theme is consistent with the main Codewars platform.

---

Major Issues

• JavaScript CW-2 Testing Framework Documentation is not 100% up-to-date. Documentation should make mention of recently added Test.assert(Not)ApproxEquals methods (and any other methods that aren't documented yet). For example, for Test.assertApproxEquals, the description could be something along the lines of: "Checks that the actual value approximates to the expected value by using a suitable epsilon (1e-9). When Math.abs(expected) <= 1, the epsilon is treated as an absolute error margin (Fix Test.assert(Not)ApproxEquals codewars-runner-cli#435); otherwise, it is treated as a relative error margin and scaled up accordingly. This method is specifically designed for comparing two real numbers, specifically floats - any attempt to compare other types of values may lead to unexpected results."
• https://kazk.github.io/codewars.com/about/beta-kata-process/ - "Kata Approval" - The statement "After a kata has received 5 approval votes from the community, fixed any issues, and reached a consensus on it’s ranking, it’s ready for the final step to come out of beta." is an oversimplification of the requirements for a Kata to leave Beta; specific requirements for each case should be listed here to avoid potential confusion among less experienced Codewars users. @kazk Perhaps you could include your table in this section of the documentation?

Minor Issues

• https://kazk.github.io/codewars.com/cookbook/testing/restricting-solution/ - "Discussion" - "The above method fails if the user's solution modifies the soltion.txt" - soltion.txt should be modified to solution.txt
• https://kazk.github.io/codewars.com/about/beta-kata-process/ - "Earning Honor on Beta Kata" - This section is slightly oversimplified and perhaps not 100% accurate? This section should (1) explain fully how those 2 honor points arise (e.g. 1 honor point for giving it a "Very/Somewhat/Not Satisfied" vote and 1 honor point for ranking it) and (2) mention that just completing a Kata while in Beta yields 3 (needs clarification) Honor Points.

Even Better If

• External links open with a new tab. Example: https://kazk.github.io/codewars.com/languages/php/phpunit/ - The link to the PHPUnit official website should have a target="_blank" attribute
• https://kazk.github.io/codewars.com/languages/javascript/cw-2/ - "Helpers" - The range of random integers that Test.randomNumber returns and the format of the string that Test.randomToken returns could be mentioned
• https://kazk.github.io/codewars.com/about/beta-kata-process/ - "Kata Approval" - Perhaps the term "moderator" could be elaborated on? Completely optional 😄
• https://kazk.github.io/codewars.com/about/honor/ - "Honor is earned fastest through creating kata ... " - perhaps we could rewrite this as "Honor is earned fastest through creating high-quality Kata"? Just a personal concern of mine, but I wouldn't want a large number of new, inexperienced users to see this sentence in the Docs and start authoring a ton of low-quality Kata.

---

Okay I've got other stuff to do now so I'm afraid I'll have to stop here. Below are the pages that I have reviewed before compiling the report above:

• All JavaScript related documentation
• All PHP related documentation
• All links provided in the "About" section

[kazk]

@DonaldKellett Thanks!

Most of the documentation under /about/ is simply outdated because I haven't touched (except for fixing typos), maybe I should put them under _drafts/ for now. I did that for some other files, but I needed few files to be listed when visiting /about/ to confirm that template logic is correct. Many of them also need rewrites in general.

@kazk Perhaps you could include your table in this section of the documentation?

Yeah, that table is now confirmed, so I'll include them. I left a comment in that file :)

Once the license is chosen, we'll be accepting contributions from the community to improve the overall quality of the documentation.

• External links open with a new tab

Good point 👍 I didn't see this.

---

Do you have any suggestions on additional contents?

• What can be useful for beginners?
• FAQs?

[Voileexperiments]

What can be useful for beginners?

Random tests? In beta it's quite often to see people, upon being asked to add random tests, raises the question of "how do I write random tests". We definitely need a good tutorial on this, maybe putting under here.

There's one tutorial in the wiki page but it's back from 2 years ago, and the way it's written is pretty cryptic to beginners (like, seriously, the use of --> operator?)

[DonaldKellett]

As @Voileexperiments mentioned, how to write random tests is both useful for beginners and an FAQ raised by many new Kata authors. With regards to this, I have found this link particularly helpful in explaining how to write basic random tests for a wide range of Kata as its code examples are very simple and clear. However, I would not recommend the new Docs linking to this document as its only source of code examples for random tests as this document is not without its own flaws. For example, all of the code examples in that document pass the random input into the user solution before passing it into the reference solution which allows for potential cheats by actively modifying the input passed in. Furthermore, their code examples have the reference solution in the global scope which again isn't ideal as the user can then use the reference solution directly in their own solution. For the code example(s) used in the new Docs regarding writing random tests, I would recommend writing our own code example(s) from scratch, taking great care to display all best practices for writing random tests, such as making use of spec methods (Test.describe, Test.it), defining the reference solution in a closure instead of in the global scope and passing the randomly generated input to the reference solution before the user's. As for the context in those code examples, we could display one code example per data type (numbers, strings, booleans, arrays and objects) for fictional Kata that are no harder than 8 kyu to prevent users from searching for a relevant Kata after looking at the examples and using the solution(s) displayed in the code examples to pass such Kata effortlessly. For examples, for the Numbers example, we could model the random tests around a fictional 8 kyu Kata called "Addition" (much like the 8 kyu "Multiply") and for the Arrays example, we could model the random tests around another fictional 8 kyu Kata called "Remove Threes from an Array".

As for other potential FAQs, another one that immediately comes to mind is "Why are the tests failing even though I have printed the correct results to the console?" Some users new to Codewars may be unfamiliar with the testing method used by the platform and may incorrectly think that the STDOUT of the program is tested in the test cases instead of the return value. After all, websites that programmers use to train on their programming skills other than Codewars almost exclusively pass in program input via file reading and test for program output via STDOUT which IMHO is very unnatural (but unfortunately is the norm for some reason). Anyway, I digress 😛

[kazk]

Problems I see in most of current documentation are:

• outdated information
• author-centric
• lack of focus
• verbosity

For example, https://www.codewars.com/topics/kata-best-practices.
Why is this under "Forum"?

"Follow Conventions" section is full of irrelevant information (or only contains irrelevant information).

"Use Behavioral Driven Development (BDD) Testing" is not "general criteria" and examples are unnecessarily complicated.

"Have Full Code Coverage" section doesn't explain anything and assumes that the reader understands Haskell. Those who can understand this section doesn't need this section. Same kind of assumptions for "Test for Invariants".

[javatlacati]

It also would be nice to add something about coding style conventions to the docs

[kazk]

I'm going to close this because we've decided to use the wiki until we have resources to work on the new documentation site.

Adding some tutorials for the beginners will be great and "How to write random tests" (with simple examples) is a good start because I see people asking all the time. Please feel free to contribute.