From 47d3756a547ada1a5054f43da71c84cfaf93d60e Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 01:07:09 +0100 Subject: [PATCH 01/28] Migrated from old wiki --- content/authoring/kata/create-first-kata.md | 262 ++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 content/authoring/kata/create-first-kata.md diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md new file mode 100644 index 00000000..d1549330 --- /dev/null +++ b/content/authoring/kata/create-first-kata.md @@ -0,0 +1,262 @@ + + + +# Creating your first kata + +Okay, so you might have completed many (all?) of the published katas on Codewars. But... that's only half of the battle. + +There is an obvious elephant in the room: Where do the katas come from? Obviously they didn't come out of nowhere like inside a stone or from a big bang, so clearly someone, or *something*, must have created the kata. + +Being intrigued, you looked at the [[Kata Creator|Kata-Creator]] again. Maybe you should create a kata. + +Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. + +While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever. You don't want that. + +--- + +## Use a novel/unique idea, avoid creating duplicate katas +At the time of writing, there are already **over 3500** published katas, and almost 3000 beta katas. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` i.e `100%` that someone will have done this before you. + +This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz katas out in the wild. When a duplicate is found it will be "retired", which basically means it gets taken out of the kata catalog. + +### How to not step on the minefield of duplicate katas + +### Search for keywords to see if someone has done the idea before +As we all know, before you even engage your enemies, you need to send scouts forward. + +For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly shows, they've been done many times already. + +In a way, knowing the katas in the wild is very similar to knowing your enemies: you get to see how others write the same kata, other people's (sometimes) brilliant solution in these katas. + +Then, maybe you can decide whether to retreat, or make a **harder** version of the kata as return if you feel the existing one is too lackluster/easy. + +### Use a novel/original idea + +If you find yourself worrying about hitting duplicates all the time, then try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas are hard! But if you can make sure your ideas are always novel and/or original, then you can be almost certain nobody will have taken the flag before you. + +It also has a side benefit of making people think that you're clever, which will be reflected on the [[satisfaction rating|Satisfaction Rating]]. + +### Solve more katas +Naturally, when you've already solved 10 fibonacci katas, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) + +### Solve more katas (again) +While the minimum honor for creating a kata is merely 300 honor, if you try to create a kata with just 300 honor, it'll most likely inadvertently be bad. + +Why? With just 300 honor, you haven't even get a grasp of what katas are actually like. + +Anyone can reach 300 honor in a very short time, from a few hours to a day or two. This is, obviously, far from enough. Thus, you need to train more. + +Solving more kata with more experiences can help one very significantly on these aspects: + +- Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. +- As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf katas: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) +- Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from the history, and don't make the same mistake again! +- Looking at solutions (and more importantly, solution comment sections) will give you insight to what'd be good practice +- It also allows you to see how others write their tests. Writing good tests are **hard**, especially if your kata is also hard. + +--- + +## Assess the right quality for the right kind of kata + +Before you start actually writing the requirements and the tests, you need to ask yourself: + +- Which kind of kata does this kata belongs to? +- What do I want to assess the users on in this kata? + +Getting these questions answered yourself will help you pinpointing the kind of solution and tests you need to write, and the overall difficulty of the kata. + +Katas are usually divided into several categories: + +### Fundamentals +Fundamental katas are easy problems intended to teach people basic aspects of programming and concepts. They consist of pretty much all the white katas, and some `6kyu` katas. + +Since they're going to be faced by lots of inexperienced users on CodeWars, everything should be clear, concise and complete, and there should also be clear feedback. You want to teach them and help them learn, not suffocating them with harsh, unforgiving material. + +Good qualities in fundamental katas include: +- A well-written and concise description explaining the concept +- Links to necessary resources +- Good example tests +- Responsive test feedbacks and full coverage of edge cases + +These things will immensely help people not familiar with the subject in question to grasp the concept. + +### Bugfix +Bugfix katas are not like your regular katas: instead of coding a solution up from scratch, a piece of code is already provided; however, it is not passing some of the requirements because of a reason, and you need to modify the code (hence bugfix) to make it work. + +Good qualities in bugfix katas include: +- Already comprehensive example tests to give users a basis for fixing the bug +- Initial code that complies to the code convention for the language +- Featuring a central, key concept +- Especially better if such concept is a very common but subtle pitfall to even experienced programmers + +However, because some people thought that bugfix kata is subjected to lower requirements than normal katas, there had been lots of bad bugfix katas. These things are what you **shouldn't do in bugfix katas**: + +- A "pseudo-code" program written in unknown, self-invented syntax that will not even compile at all +- Highly obfuscated or ugly programs + +Basically, if a bugfix kata features code that is so smelly rewriting it from scratch would be more pleasant and faster, it stops being a bugfix kata and becomes a regular kata. + +### Algorithm +Algorithm katas, as it's named, test the user on writing a good algorithm for the task in question. How good an algorithm needs to be, or how hard it is to come up with the algorihm, varies from problem to problem. They might also have varying degrees of performance requirements. + +Good qualities in algorithm katas include: +- A clear description of the problem +- Thorough tests, excellent coverage and complete testing of edge cases +- If performance is required, specify the input range and number of tests + +### Puzzles +Puzzle katas are not your regular katas. They are more like actual puzzles and games - the coding part might be very easy even for beginners, but it is not apparent what the steps are. Puzzle katas also generally includes recreational programming puzzles - code golf, source restrictions, environment investigation, cop and robbers, etc. + +Good qualities in puzzle katas include: +- Actually being a puzzle (i.e don't give big, big hints right away) +- Well-designed and coherent puzzles +- Subtle but adequately planted hints +- Puzzle elements that are not finicky - if a user gets the puzzle, he should not need to do lots of fumbling and trial-and-error to get them to work + +Needless to say, it requires lots of ingenuity to pull off a puzzle kata. It's not for the faint of heart - it's very easy to make a puzzle kata that is a "guess the author's intent" kata, or a "trivial puzzle" kata. They're not very interesting. + +### Challenges +Challenges katas are very, very tough problems intended to give a challenge to even the veterans, which are, by their nature, difficult to be challenged (otherwise they wouldn't be "veterans"), so one has to go really far to impress them. + +Naturally, a challenge kata should not just require people to code brainlessly and pass in a few minutes. It should not just be tough to newbies - it should be tough even to experts. + +Good qualities in challenge katas include: +- A good description to present the problem +- Require lots of experience and/or background research to even figure out the possible approaches +- Require careful planning to formulate a line of attack +- Even with that, might still require hard work and clever approaches to succeed + +Things that you should avoid in challenge katas: +- Total lack of mercy. If you require everyone to write the fastest micro-optimized solution, then only the fastest micro-optimized solution will pass. There should at least be *some* leeway so people don't have to, again, juggle 10 things at once and get annoyed +- Difficulty by obscurity. Inflating challenges with "guessing the intent" is never a good practice. See also: the point in "Puzzle kata" above + +Remember, after all the best challenging puzzles are not about puzzles, they're about *experiences*. When you can craft puzzles that makes people experience and remember the process of figuring it out, you'll have truly become the master. This is what people mean when they say "when I finally solved this I felt very satisfied". + +### Projects + +Projects are kata that are about implementing an actual, working product according to specifications. They almost always require to juggle several things at once. The product can range from anything small to big - a custom helper class, to a full-blown interpreter/solver or engine. + +Good qualities of project katas include: +- A good intention/introduction opening to tell people *why* such project would be useful +- Well-written, well-organized and clear specifications +- Thorough tests that are broken into pieces (i.e unit tests) so that people can test one aspect/component at a time + +A good project kata can teach people how to build up a full, working project that solves a general problem from scratch, instead of just a tiny program that solves a very specific and narrow task. + +--- + +## Be clear about the intent, and write good descriptions +Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? + +Don't let yourself be the guy who wrote this. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your katas, and nobody will finish them at all. + +A description should: +- Provide a sufficient and complete description and requirements of the task +- If it provides some back-story, it shouldn't be so long that it overwhelms the kata itself +- If complex steps are involved, give an actual step-by-step example +- Lists all the edge cases, edge conditions and required error handling if they're required +- Be structured well so that people can read from top to bottom as they implement the requirement sequentially +- Make proper use of Markdown to convert walls of text to more readable formatting, e.g paragraphs, lists, code blocks +- Highlight really important things (e.g `round to 2 decimal places`) in emphasis, e.g in bold + +An extensive use of Markdown will significant help the readability of the descriptions. Codewars uses an expanded version of GF Markdown so make sure to check the [[documentation|Markdown-Formatting]]. + +Fortunately, if your kata description is not very good, people will be eager to point this out in the comments, so you have more than enough chances to fix them. + +Additionally, if you're writing performance/algorithm katas, you should provide the data range. It helps people to gauge how good their solution needs to be. + +Incidentally, "guess your intent", or guessing in general, is seldom a good puzzle. It requires very delicate skills and experience to pull off well. If you are going to attempt this, please make sure to seek out other kata and learn from what works and what doesn't. + +## Stick to the intent, focus on one key thing per kata +If you ask people to do 10 katas about 10 different things, that's okay. + +But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 object at once is not fun. + +This often happens for unbalanced katas - while they're asking for doing one thing, because of how the kata is written the actual difficulty lies on something **completely unrelated** to the proposed intent of the kata itself, e.g doing a task with a very unnatural and hard to work with input format. + +If you find that your kata is too long, mostly from these symptoms: +- your kata has a very long description +- a typical solution is very long and yet none of them is hard, the only difficulty is from the tediousness +- your kata requires doing many things together, + +you might want to break up your kata in separate parts if appropriate. + +Quoting power user @JohanWiltink's comment on one of the beta katas: + +> And, again, you're doing multiple unrelated things in one kata. Totally unrelated, neither of them trivial this time. What is the intent, what is the pointe of this kata? +> +> (Please note: a pointe is not a point. I'm not implying this kata is pointless. If anything, it seems overpointed - in width, not in depth.) + +--- + +## Provide the solver with an Initial Solution that compiles + +Imagine the following scenario (assuming a statically typed language): you train on a Kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the Kata description and Sample Test Cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the Initial Solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? + +_Unless_ the focus of your Kata is debugging (and how often do you encounter debugging Kata that are even remotely enjoyable?) or your Kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the Initial Solution just to get it to compile. The Initial Solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that (s)he can start replacing the dummy implementations with his / her own code straight away. **It is a Kata issue if the Initial Solution fails to compile, especially if it introduces unnecessary overhead for the solver.** + +Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the Initial Solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. + +--- + +## Write good tests, and utilize both fixed and random test cases +While the old katas are usually lazy and only has a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. + +The key thing about tests is that a test should perform two things: +1. Accept all conforming solutions +2. Reject all non-conforming solutions + +Some people might think that only point 1 is necessary, which is obviously untrue: test that accepts **everything** is pointless. Good tests will let the correct solutions -- *and only* the correct solutions -- pass. + +For normal katas, a good set of tests should cover all of these aspects: +- Test basic functionality +- Has full coverage (if that's impossible, at least have decent coverage) +- Cover edge cases thoroughly +- Randomized tests to probe user solution with random samples (and so that pattern-matching against the tests is impossible) +- Stress/performance/code characteristic tests if needed + +The first three should be put into fixed tests. The fourth item should be put into random tests. Ideally the last item would be in isolation, or covered by random tests. The last item is optional. + +### An additional note on sample tests + +Sample tests are not required in general, but you should provide sample test cases. These are some basic test cases that users will see when they load the kata. + +You can include a few tests to get someone started, though of course if you're lazy you can just copy the fixed test cases from the actual tests over there. Just don't copy your reference solution there as well. + +Unless you intend the users to write tests themselves, or such is not applicable for your kata (Example: [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), it's usually considered a good practice to provide example test cases to the users. + +### An additional note on random tests + +![](https://imgs.xkcd.com/comics/random_number.png) + +###### (Source: [xkcd](https://xkcd.com/221/)) + +Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for warriors to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. + +### Points that floats around + +If your test involves comparing two floating point numbers, note that due to the nature of floating point numbers, arithmetic expressions with the same result but expressed differently will generally incur tiny errors between them. Hence you should never ever check if they're equal. Instead, you should check if two numbers are equal by a tiny threshold. + +Some languages' test frameworks have the corresponding test functions to do this, e.g JavaScript's `Test.assertApproxEquals`. You should really [[consult the testing framework|Languages-and-Test-Frameworks]] for your language, or roll one yourself. The logic is roughly as: + +``` +Suppose we already have the expected and actual value, and the threshold. + +if abs(expected) <= threshold: then we check abs(expected - actual) < threshold +else: we check abs((expected - actual) / expected) < threshold + +(abs is the absolute value function). +``` + +The threshold is usually around `1e-10` to `1e-12`, though depending on the situation at hand this can easily go up to `1e-4`, especially for numerical computation tasks. + +### Test feedback + +Remember: just like in real life, if we failed a test, we want to know: +- what was the input +- expected and actual result + +So unless revealing the expected result would spoil the kata, you should not hide them. [[Consult the testing framework|Languages-and-Test-Frameworks]] and pick the best method for your tests. (Protip: `expect` is almost never the best pick.) + +...Yes, who said writing tests are easy? Learning how to use the testing framework properly is part of learning how to code! From f56aad4c3b20adedc437649cb54a60eced04f6da Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 01:26:55 +0100 Subject: [PATCH 02/28] Navigation --- content/authoring/kata/create-first-kata.md | 5 ++++- gridsome.config.js | 6 ++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index d1549330..b73872c1 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -1,4 +1,7 @@ - +--- +kind: tutorial +sidebar: authoring +--- # Creating your first kata diff --git a/gridsome.config.js b/gridsome.config.js index 710ab23f..b72000f4 100644 --- a/gridsome.config.js +++ b/gridsome.config.js @@ -127,6 +127,12 @@ module.exports = { "/authoring/guidelines/kata/", ], }, + { + title: "Tutorials", + items: [ + "/authoring/kata/create-first-kata/", + ], + }, ], }, { From 0d66c613eb8b6351a87d5817aadc9bce54597e21 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 00:27:26 +0000 Subject: [PATCH 03/28] Autoformat with Prettier --- gridsome.config.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/gridsome.config.js b/gridsome.config.js index b72000f4..e42f7290 100644 --- a/gridsome.config.js +++ b/gridsome.config.js @@ -129,9 +129,7 @@ module.exports = { }, { title: "Tutorials", - items: [ - "/authoring/kata/create-first-kata/", - ], + items: ["/authoring/kata/create-first-kata/"], }, ], }, From b64f7c7a3399c7637bc36fa53dc70d4d7758859c Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 01:39:49 +0100 Subject: [PATCH 04/28] Organization, navigation --- content/authoring/index.md | 30 +++----------------------- content/authoring/kata/index.md | 15 ++++++++++--- content/authoring/translation/index.md | 13 ++++++++--- 3 files changed, 25 insertions(+), 33 deletions(-) diff --git a/content/authoring/index.md b/content/authoring/index.md index 2a69ad11..733d5190 100644 --- a/content/authoring/index.md +++ b/content/authoring/index.md @@ -5,38 +5,14 @@ next: /authoring/kata/ # Authoring of Codewars Content -## Overview - All content available on Codewars is created by members of the Codewars community. It's ideas of Codewars users that get turned into kata, and only the fact that users are familiar with plenty of programming languages allows for a large number of available translations. This section of the documentation is meant mostly for authors and translators, who would like to introduce new challenges and make them available for other Codewars users. Creating a kata or translating it, even an easy one, is a difficult task. It requires a much wider set of skills compared to the one required for just solving a kata. Unlike problem solvers, authors need to master skills related to software development in general, as well as to design of the problems, writing good test suites, documenting the task and its requirements, and communicating with reviewers. To support users in creating good quality kata and translations, a set of help pages were created with articles related to content authoring activities: tutorials explaining how to create and translate a kata, and a reference of [guidelines][guidelines-authoring] and requirements that every author should follow to make sure that a piece of content created by them meets quality criteria. -## Creating a Kata - -_TBD: improve this stub_ - -Users new to creating kata can use [tutorial(TODO)](/authoring/kata/). - -Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. - -Every kata author should follow [kata authoring guidelines](/authoring/guidelines/kata/). - -After being published, every kata goes through the [beta process](/concepts/kata/beta-process/) and is subject to a series of [reviews](/curating/kata/). - -## Translating a Kata - -_TBD: improve this stub_ - -New translators can use [tutorial(TODO)](/authoring/translation/). - -Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. - -Every translator should follow [translation authoring guidelines](/authoring/guidelines/translation/). - -After being published, every translation goes through a series of [reviews](/curating/translation/) before it can be approved. - +For more details, see help pages related to creating a specific type of content: +- [Creating a kata](/content/authoring/kata/) +- [Creating a translation](/content/authoring/translation/) [guidelines-authoring]: /authoring/guidelines/ -[docs-curating]: /curating/ diff --git a/content/authoring/kata/index.md b/content/authoring/kata/index.md index c77632dd..f2d8f16b 100644 --- a/content/authoring/kata/index.md +++ b/content/authoring/kata/index.md @@ -1,12 +1,21 @@ --- -kind: tutorial sidebar: authoring next: /authoring/ prev: /authoring/translation/ --- -# How to create a kata +## Creating a Kata -_This page is a stub._ +_TBD: improve this stub_ +Users new to creating kata can use [tutorial(TODO)](/authoring/kata/). +Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. + +Every kata author should follow [kata authoring guidelines](/authoring/guidelines/kata/). + +After being published, every kata goes through the [beta process](/concepts/kata/beta-process/) and is subject to a series of [reviews](/curating/kata/). + + + +[docs-curating]: /curating/ diff --git a/content/authoring/translation/index.md b/content/authoring/translation/index.md index 7d6f945d..986e08a7 100644 --- a/content/authoring/translation/index.md +++ b/content/authoring/translation/index.md @@ -1,13 +1,20 @@ --- -kind: tutorial sidebar: authoring prev: /authoring/kata/ next: /authoring/guidelines/ --- -# How to translate a kata +## Translating a Kata -_TBD: this page was imported from the old CW wiki and needs to be reviewed/redacted._ +_TBD: improve this stub_ + +New translators can use [tutorial(TODO)](/authoring/translation/). + +Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. + +Every translator should follow [translation authoring guidelines](/authoring/guidelines/translation/). + +After being published, every translation goes through a series of [reviews](/curating/translation/) before it can be approved. ## Be clear about the intent, and write good descriptions + Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? Don't let yourself be the guy who wrote this. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your katas, and nobody will finish them at all. @@ -171,7 +195,9 @@ Additionally, if you're writing performance/algorithm katas, you should provide Incidentally, "guess your intent", or guessing in general, is seldom a good puzzle. It requires very delicate skills and experience to pull off well. If you are going to attempt this, please make sure to seek out other kata and learn from what works and what doesn't. + ## Stick to the intent, focus on one key thing per kata + If you ask people to do 10 katas about 10 different things, that's okay. But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 object at once is not fun. @@ -191,7 +217,6 @@ Quoting power user @JohanWiltink's comment on one of the beta katas: > > (Please note: a pointe is not a point. I'm not implying this kata is pointless. If anything, it seems overpointed - in width, not in depth.) ---- ## Provide the solver with an Initial Solution that compiles @@ -201,9 +226,9 @@ _Unless_ the focus of your Kata is debugging (and how often do you encounter deb Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the Initial Solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. ---- ## Write good tests, and utilize both fixed and random test cases + While the old katas are usually lazy and only has a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. The key thing about tests is that a test should perform two things: @@ -221,6 +246,7 @@ For normal katas, a good set of tests should cover all of these aspects: The first three should be put into fixed tests. The fourth item should be put into random tests. Ideally the last item would be in isolation, or covered by random tests. The last item is optional. + ### An additional note on sample tests Sample tests are not required in general, but you should provide sample test cases. These are some basic test cases that users will see when they load the kata. @@ -229,14 +255,14 @@ You can include a few tests to get someone started, though of course if you're l Unless you intend the users to write tests themselves, or such is not applicable for your kata (Example: [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), it's usually considered a good practice to provide example test cases to the users. -### An additional note on random tests -![](https://imgs.xkcd.com/comics/random_number.png) +### An additional note on random tests -###### (Source: [xkcd](https://xkcd.com/221/)) +![(Source: [xkcd](https://xkcd.com/221/))](https://imgs.xkcd.com/comics/random_number.png) Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for warriors to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. + ### Points that floats around If your test involves comparing two floating point numbers, note that due to the nature of floating point numbers, arithmetic expressions with the same result but expressed differently will generally incur tiny errors between them. Hence you should never ever check if they're equal. Instead, you should check if two numbers are equal by a tiny threshold. @@ -254,6 +280,7 @@ else: we check abs((expected - actual) / expected) < threshold The threshold is usually around `1e-10` to `1e-12`, though depending on the situation at hand this can easily go up to `1e-4`, especially for numerical computation tasks. + ### Test feedback Remember: just like in real life, if we failed a test, we want to know: @@ -263,3 +290,7 @@ Remember: just like in real life, if we failed a test, we want to know: So unless revealing the expected result would spoil the kata, you should not hide them. [[Consult the testing framework|Languages-and-Test-Frameworks]] and pick the best method for your tests. (Protip: `expect` is almost never the best pick.) ...Yes, who said writing tests are easy? Learning how to use the testing framework properly is part of learning how to code! + + +_TODO: Announcing a kata and asking for feedback_ +_TODO: Responsibility and maintenance_ \ No newline at end of file From c93dad87567e2635781bdb57f69019fc5fc4ce00 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 16:23:14 +0100 Subject: [PATCH 07/28] Organization --- content/authoring/kata/create-first-kata.md | 108 +++++++++++++++++- content/authoring/kata/img/new_kata-dark.png | Bin 0 -> 14909 bytes content/authoring/kata/img/new_kata-light.png | Bin 0 -> 16188 bytes content/authoring/kata/index.md | 13 ++- content/authoring/translation/index.md | 2 +- content/references/ui/kata-editor/index.md | 15 --- 6 files changed, 115 insertions(+), 23 deletions(-) create mode 100644 content/authoring/kata/img/new_kata-dark.png create mode 100644 content/authoring/kata/img/new_kata-light.png diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 61c9bb9d..119e4e13 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -10,14 +10,112 @@ Okay, so you might have completed many (all?) of the published katas on Codewars There is an obvious elephant in the room: Where do the katas come from? Obviously they didn't come out of nowhere like inside a stone or from a big bang, so clearly someone, or *something*, must have created the kata. -Being intrigued, you looked at the [[Kata Creator|Kata-Creator]] again. Maybe you should create a kata. +Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. What authors sometimes do not realize is the fact that creating a good quality kata is much harder than solving it. -Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. +While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever, collecting negative feedback through the time. You don't want that. -While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever. You don't want that. -_TODO: How to enter the kata creator view, kata editor reference_ -_TODO: Stick to guidelines (redact or remove redundant parts from this article)_ +## Support for authors + +To support you with this difficult task, a set of help pages has been created with following types of information: +- [tutorials](/tutorials/), for users who are still figuring things out, +- [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will meet with bad reception, harsh remarks, and many reported issues. +- [HOWTOs](/recipes/) explaining how to realize some commonly occuring tasks, or solve commonly repeating problems, +- [Language specific pages](/languages/) with code snippets, examples, and information related to specific programming languages. + +You can also reach directly to community to ask questions and seek for advice of experienced users on [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter chat. + + +## Requirements + +To create a new kata, you need to earn the ["Create Kata" privilege](/references/gamification/privileges/). After reaching the required amount of Honor, the privilege is granted and you can select the **"New Kata"** option from their profile menu: + +
+ +![Allies board on user dashboard](./img/new_kata-light.png) + +
+ + + +## Setting up the kata + +Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/#what-is-the-kata-editor). To fully set up the kata you have to provide some basic information, as well as to write some code in language(s) of your choice. + + +### Kata Properties + +#### Name + +The name is used to uniquely identify a kata. You can be creative with the name that you use. Best practice is to use a name that gives other users a good idea of what type of challenge they will be getting themselves into. + + +#### Discipline + +The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are four categories: + +- Fundamentals - Focuses on core language and API knowledge. +- Algorithms - Focuses on the logic required to complete the task. +- Bug Fixes - Focuses on taking existing code, determining the issue and fixing it. +- Refactoring - Focuses on taking existing code and making it better. +- Puzzles + + +#### Estimated rank + +_TBD_ + + +#### Tags + +_TBD_ + + +#### Allow Cntributors? + +_TBD_ + + +### Description + +The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [[Github/Codewars flavored markdown|Markdown-Formatting]]. You can use the preview tab to see the markdown. + +For complex katas you may need to create a lengthy description in order to fully describe the requirements. For easier katas it is best to keep the description as short and concise as possible. Feel free to use code block examples within the description. It is always best to use the three back tick (```) code block style instead of indentation. + + +### Code Snippets + +_TBD: intro_ + + +#### Complete Solution + +When creating your kata you will probably want to start with the final solution and test fixture code blocks. If you are used to TDD then you will write your tests within the test fixture and then you will create a fully working solution within the final solution code block. If you need to load some preloaded code then you may need to do that before working on the final solution code block. + +#### Initial Solution + +After you have a working solution then you will want to next focus on getting the code setup for how other users will initially see it. The way in which you setup your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include almost working or already fully working code within this block. For reference and algorithm disciplines you will likely only include skeleton code. Perhaps an empty function/method called "solution" or some other code that has missing code that needs to be completed. Sometimes you may just want to include some comments to help get the user started, but no actual code. + +The initial solution block is required so you will have to include something (at the very least some comments) in order for the kata to be able to be published. + +#### Preloaded + +The preloaded code block is an optional feature that you can use if you need it. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example maybe you want to create a kata that asks a user to add an item to an array. It would be better to define the array within the preloaded code block so that the user already has the array created for them, and will be more likely to just add an item to the array using the appropriate array method, instead of updating the array constructor to include the value (and bypassing using an array method all together). + +#### Test Cases + +The test fixture is used to write code that will validate the kata solution. +The entire set of code in this block acts as a single test case. To validate solution code +you can use the Test.expect(passed_boolean, optional_message) method. More advanced testing methods are also available. Check out the kata test framework documentation for more information. + + +#### Example Test Cases + +_TBD_ ## Use a novel/unique idea, avoid creating duplicate katas diff --git a/content/authoring/kata/img/new_kata-dark.png b/content/authoring/kata/img/new_kata-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..75c892921c1e82ac1684a8e4ffaf52846ec95410 GIT binary patch literal 14909 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 DM3A(A literal 0 HcmV?d00001 diff --git a/content/authoring/kata/img/new_kata-light.png b/content/authoring/kata/img/new_kata-light.png new file mode 100644 index 0000000000000000000000000000000000000000..e060bb956914ebcdd5301069f5be09b5be1d25d3 GIT binary patch literal 16188 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 literal 0 HcmV?d00001 diff --git a/content/authoring/kata/index.md b/content/authoring/kata/index.md index f2d8f16b..2e83f470 100644 --- a/content/authoring/kata/index.md +++ b/content/authoring/kata/index.md @@ -4,10 +4,19 @@ next: /authoring/ prev: /authoring/translation/ --- -## Creating a Kata +# Kata _TBD: improve this stub_ +## Requirements + +To create a new kata, a user needs to earn the ["Create Kata" privilege][reference-privileges]. After reaching the required amount of Honor, the privilege is granted and the user can select the **"New Kata"** option from their profile menu. + + +## Kata Editor + +Kata are created by filling the + Users new to creating kata can use [tutorial(TODO)](/authoring/kata/). Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. @@ -17,5 +26,5 @@ Every kata author should follow [kata authoring guidelines](/authoring/guideline After being published, every kata goes through the [beta process](/concepts/kata/beta-process/) and is subject to a series of [reviews](/curating/kata/). - +[reference-privileges]: /references/gamification/privileges/ [docs-curating]: /curating/ diff --git a/content/authoring/translation/index.md b/content/authoring/translation/index.md index 986e08a7..23e2844a 100644 --- a/content/authoring/translation/index.md +++ b/content/authoring/translation/index.md @@ -4,7 +4,7 @@ prev: /authoring/kata/ next: /authoring/guidelines/ --- -## Translating a Kata +# Translations _TBD: improve this stub_ diff --git a/content/references/ui/kata-editor/index.md b/content/references/ui/kata-editor/index.md index 5cfab437..a8f4ec39 100644 --- a/content/references/ui/kata-editor/index.md +++ b/content/references/ui/kata-editor/index.md @@ -38,21 +38,6 @@ The description field is used to provide instructions to the users who will be t For complex katas you may need to create a lengthy description in order to fully describe the requirements. For easier katas it is best to keep the description as short and concise as possible. Feel free to use code block examples within the description. It is always best to use the three back tick (```) code block style instead of indentation. -### Describing code examples for multiple languages - -The markdown we provide adds an additional feature useful for displaying code blocks of multiple languages. If you use the ``` [language name] markdown format for indicating which code syntax should be used then you can define all of the languages examples within the description field. When your markdown is displayed it will filter out the languages that are not relevant (based off of the current context). In order for this to work you must use the language's full name and have your examples grouped together without any additional content in between them. - -The following is an example of how to provide example code blocks for both javascript and coffeescript: - -~~~ -```javascript -var a = [] -``` -```coffeescript -a = [] -``` -~~~ - ### Final Solution When creating your kata you will probably want to start with the final solution and test fixture code blocks. If you are used to TDD then you will write your tests within the test fixture and then you will create a fully working solution within the final solution code block. If you need to load some preloaded code then you may need to do that before working on the final solution code block. From 0cb3441edecc64ffcc62a7fec5ee5e9fb7e685a7 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 7 Jan 2021 16:46:49 +0100 Subject: [PATCH 08/28] Organization --- content/authoring/kata/create-first-kata.md | 9 +++-- content/references/ui/kata-editor/index.md | 42 --------------------- 2 files changed, 5 insertions(+), 46 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 119e4e13..54f31c63 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -32,19 +32,19 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references
-![Allies board on user dashboard](./img/new_kata-light.png) +!["New Kata" menu command](./img/new_kata-light.png)
## Setting up the kata -Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/#what-is-the-kata-editor). To fully set up the kata you have to provide some basic information, as well as to write some code in language(s) of your choice. +Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/). To fully set up the kata you have to provide some basic information, as well as write some code in language(s) of your choice. ### Kata Properties @@ -391,4 +391,5 @@ So unless revealing the expected result would spoil the kata, you should not hid _TODO: Announcing a kata and asking for feedback_ -_TODO: Responsibility and maintenance_ \ No newline at end of file +_TODO: Responsibility and maintenance_ +_TODO: Common pitfalls_ \ No newline at end of file diff --git a/content/references/ui/kata-editor/index.md b/content/references/ui/kata-editor/index.md index a8f4ec39..bb15ddbe 100644 --- a/content/references/ui/kata-editor/index.md +++ b/content/references/ui/kata-editor/index.md @@ -15,45 +15,3 @@ next: /references/ui/kata-trainer/ The Kata Editor is the authoring tool used to create and modify kata. It is accessible through the profile menu, found in the top right corner of this site. Only users who have earned the [[Create Kata|Privileges]] privilege. -## Anatomy of a Kata - -In order to create a kata you must first understand the elements of a kata. - -### Name - -The name is used to uniquely identify a kata. You can be creative with the name that you use. Best practice is to use a name that gives other users a good idea of what type of challenge they will be getting themselves into. - -### Discipline - -The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are four categories - -- Reference - Focuses on core language and API knowledge. -- Algorithm - Focuses on the logic required to complete the task. -- Bug Fix - Focuses on taking existing code, determining the issue and fixing it. -- Refactor - Focuses on taking existing code and making it better. - -### Description - -The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [[Github/Codewars flavored markdown|Markdown-Formatting]]. You can use the preview tab to see the markdown. - -For complex katas you may need to create a lengthy description in order to fully describe the requirements. For easier katas it is best to keep the description as short and concise as possible. Feel free to use code block examples within the description. It is always best to use the three back tick (```) code block style instead of indentation. - -### Final Solution - -When creating your kata you will probably want to start with the final solution and test fixture code blocks. If you are used to TDD then you will write your tests within the test fixture and then you will create a fully working solution within the final solution code block. If you need to load some preloaded code then you may need to do that before working on the final solution code block. - -### Initial Solution - -After you have a working solution then you will want to next focus on getting the code setup for how other users will initially see it. The way in which you setup your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include almost working or already fully working code within this block. For reference and algorithm disciplines you will likely only include skeleton code. Perhaps an empty function/method called "solution" or some other code that has missing code that needs to be completed. Sometimes you may just want to include some comments to help get the user started, but no actual code. - -The initial solution block is required so you will have to include something (at the very least some comments) in order for the kata to be able to be published. - -### Preloaded - -The preloaded code block is an optional feature that you can use if you need it. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example maybe you want to create a kata that asks a user to add an item to an array. It would be better to define the array within the preloaded code block so that the user already has the array created for them, and will be more likely to just add an item to the array using the appropriate array method, instead of updating the array constructor to include the value (and bypassing using an array method all together). - -### Test Fixture - -The test fixture is used to write code that will validate the kata solution. -The entire set of code in this block acts as a single test case. To validate solution code -you can use the Test.expect(passed_boolean, optional_message) method. More advanced testing methods are also available. Check out the kata test framework documentation for more information. \ No newline at end of file From d9c9d416119aa579f5e67bcb55aa943278f458cf Mon Sep 17 00:00:00 2001 From: hobovsky Date: Fri, 8 Jan 2021 13:42:14 +0100 Subject: [PATCH 09/28] Organization --- content/authoring/kata/create-first-kata.md | 289 +++++--------------- 1 file changed, 69 insertions(+), 220 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 54f31c63..47ac3bcc 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -21,7 +21,7 @@ To support you with this difficult task, a set of help pages has been created wi - [tutorials](/tutorials/), for users who are still figuring things out, - [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will meet with bad reception, harsh remarks, and many reported issues. - [HOWTOs](/recipes/) explaining how to realize some commonly occuring tasks, or solve commonly repeating problems, -- [Language specific pages](/languages/) with code snippets, examples, and information related to specific programming languages. +- [Language specific pages](/languages/) with code snippets, examples, references and tutorials related to specific programming languages. You can also reach directly to community to ask questions and seek for advice of experienced users on [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter chat. @@ -42,87 +42,12 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references -## Setting up the kata - -Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/). To fully set up the kata you have to provide some basic information, as well as write some code in language(s) of your choice. - - -### Kata Properties - -#### Name - -The name is used to uniquely identify a kata. You can be creative with the name that you use. Best practice is to use a name that gives other users a good idea of what type of challenge they will be getting themselves into. - - -#### Discipline - -The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are four categories: - -- Fundamentals - Focuses on core language and API knowledge. -- Algorithms - Focuses on the logic required to complete the task. -- Bug Fixes - Focuses on taking existing code, determining the issue and fixing it. -- Refactoring - Focuses on taking existing code and making it better. -- Puzzles - - -#### Estimated rank - -_TBD_ - - -#### Tags - -_TBD_ - -#### Allow Cntributors? +## Kata Idea -_TBD_ +At the time of writing, there are already **over 6500** published kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. - -### Description - -The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [[Github/Codewars flavored markdown|Markdown-Formatting]]. You can use the preview tab to see the markdown. - -For complex katas you may need to create a lengthy description in order to fully describe the requirements. For easier katas it is best to keep the description as short and concise as possible. Feel free to use code block examples within the description. It is always best to use the three back tick (```) code block style instead of indentation. - - -### Code Snippets - -_TBD: intro_ - - -#### Complete Solution - -When creating your kata you will probably want to start with the final solution and test fixture code blocks. If you are used to TDD then you will write your tests within the test fixture and then you will create a fully working solution within the final solution code block. If you need to load some preloaded code then you may need to do that before working on the final solution code block. - -#### Initial Solution - -After you have a working solution then you will want to next focus on getting the code setup for how other users will initially see it. The way in which you setup your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include almost working or already fully working code within this block. For reference and algorithm disciplines you will likely only include skeleton code. Perhaps an empty function/method called "solution" or some other code that has missing code that needs to be completed. Sometimes you may just want to include some comments to help get the user started, but no actual code. - -The initial solution block is required so you will have to include something (at the very least some comments) in order for the kata to be able to be published. - -#### Preloaded - -The preloaded code block is an optional feature that you can use if you need it. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example maybe you want to create a kata that asks a user to add an item to an array. It would be better to define the array within the preloaded code block so that the user already has the array created for them, and will be more likely to just add an item to the array using the appropriate array method, instead of updating the array constructor to include the value (and bypassing using an array method all together). - -#### Test Cases - -The test fixture is used to write code that will validate the kata solution. -The entire set of code in this block acts as a single test case. To validate solution code -you can use the Test.expect(passed_boolean, optional_message) method. More advanced testing methods are also available. Check out the kata test framework documentation for more information. - - -#### Example Test Cases - -_TBD_ - - -## Use a novel/unique idea, avoid creating duplicate katas - -At the time of writing, there are already **over 3500** published katas, and almost 3000 beta katas. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` i.e `100%` that someone will have done this before you. - -This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz katas out in the wild. When a duplicate is found it will be "retired", which basically means it gets taken out of the kata catalog. +This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz katas out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. ### How to not step on the minefield of duplicate katas @@ -167,167 +92,114 @@ Solving more kata with more experiences can help one very significantly on these - Looking at solutions (and more importantly, solution comment sections) will give you insight to what'd be good practice - It also allows you to see how others write their tests. Writing good tests are **hard**, especially if your kata is also hard. - +If you allow others to contribute to your kata, they will be able to make changes to it when it's a subject of the [beta process](/concepts/kata/beta-process/). However, even when you do not allow for contributors, sufficiently privileged users will be able to edit your kata if it has some pending issues or requires fixing. -## Be clear about the intent, and write good descriptions +You can check the list of [privileges](/references/gamification/privileges/#privileges) to see who can modify your kata. -Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? -Don't let yourself be the guy who wrote this. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your katas, and nobody will finish them at all. +### Description -A description should: -- Provide a sufficient and complete description and requirements of the task -- If it provides some back-story, it shouldn't be so long that it overwhelms the kata itself -- If complex steps are involved, give an actual step-by-step example -- Lists all the edge cases, edge conditions and required error handling if they're required -- Be structured well so that people can read from top to bottom as they implement the requirement sequentially -- Make proper use of Markdown to convert walls of text to more readable formatting, e.g paragraphs, lists, code blocks -- Highlight really important things (e.g `round to 2 decimal places`) in emphasis, e.g in bold +The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](https://docs.codewars.com/references/markdown/) with a set of [Codewars extensions](https://docs.codewars.com/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. -An extensive use of Markdown will significant help the readability of the descriptions. Codewars uses an expanded version of GF Markdown so make sure to check the [[documentation|Markdown-Formatting]]. +Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? Don't let yourself be the guy who wrote this. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your katas, and nobody will finish them at all. Fortunately, if your kata description is not very good, people will be eager to point this out in the comments, so you have more than enough chances to fix them. -Additionally, if you're writing performance/algorithm katas, you should provide the data range. It helps people to gauge how good their solution needs to be. +Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](https://docs.codewars.com/authoring/guidelines/description/) to ensure that your description is of sufficient quality. -Incidentally, "guess your intent", or guessing in general, is seldom a good puzzle. It requires very delicate skills and experience to pull off well. If you are going to attempt this, please make sure to seek out other kata and learn from what works and what doesn't. +### Code Snippets -## Stick to the intent, focus on one key thing per kata +To make your kata runnable, you need to write some code. Kata code is divided into a couple of snippets, each of them having a specific role, and being used in specific circumstances. -If you ask people to do 10 katas about 10 different things, that's okay. +To keep the kata easy to maintain, every snippet is a subject to quality guidelines, both [general](/authoring/guidelines/coding/), and a set specific for each of them. -But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 object at once is not fun. -This often happens for unbalanced katas - while they're asking for doing one thing, because of how the kata is written the actual difficulty lies on something **completely unrelated** to the proposed intent of the kata itself, e.g doing a task with a very unnatural and hard to work with input format. +#### Complete Solution -If you find that your kata is too long, mostly from these symptoms: -- your kata has a very long description -- a typical solution is very long and yet none of them is hard, the only difficulty is from the tediousness -- your kata requires doing many things together, +You need to provide a solution to your own kata, to prove that it can be solved at all. Author's solution is run every time the kata is published, to verify correctness of tests and of general kata setup. -you might want to break up your kata in separate parts if appropriate. +#### Initial Solution -Quoting power user @JohanWiltink's comment on one of the beta katas: +Initial solution is what users are provided with when they start training on your kata. The way in which you setup your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include almost working or already fully working code within this block. For reference and algorithm disciplines you will likely only include skeleton code. Perhaps an empty function/method or some other code that has gaps which need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. -> And, again, you're doing multiple unrelated things in one kata. Totally unrelated, neither of them trivial this time. What is the intent, what is the pointe of this kata? -> -> (Please note: a pointe is not a point. I'm not implying this kata is pointless. If anything, it seems overpointed - in width, not in depth.) +However, imagine the following scenario (assuming a statically typed language): you train on a Kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the Kata description and Sample Test Cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the Initial Solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? +_Unless_ the focus of your Kata is debugging (and how often do you encounter debugging Kata that are even remotely enjoyable?) or your Kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the Initial Solution just to get it to compile. The Initial Solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that (s)he can start replacing the dummy implementations with his / her own code straight away. **It is a Kata issue if the Initial Solution fails to compile, especially if it introduces unnecessary overhead for the solver.** -## Provide the solver with an Initial Solution that compiles +Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the Initial Solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. -Imagine the following scenario (assuming a statically typed language): you train on a Kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the Kata description and Sample Test Cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the Initial Solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? +The initial solution block is required so you will have to include something (at the very least some comments) in order for the kata to be able to be published. -_Unless_ the focus of your Kata is debugging (and how often do you encounter debugging Kata that are even remotely enjoyable?) or your Kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the Initial Solution just to get it to compile. The Initial Solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that (s)he can start replacing the dummy implementations with his / her own code straight away. **It is a Kata issue if the Initial Solution fails to compile, especially if it introduces unnecessary overhead for the solver.** +#### Preloaded -Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the Initial Solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. +The preloaded code block is an optional feature that you can use if you need it. The code from the preloaded snippet cannot be edited by the user, but it's available for all other snippets (solution and tests) to use. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example, it can contain classes or constants which should be common for both solution and tests. +Working with preloaded code is sometimes tricky, and that's why a set of [guidelines](/authoring/guidelines/preloaded/) related to this particular snipped is created. + +#### Test Cases -## Write good tests, and utilize both fixed and random test cases +The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them to consider the kata completed. Every language on Codewars is set up to provide you with a testing framework, which you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). -While the old katas are usually lazy and only has a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. +While the old kata are usually lazy and only have a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. The key thing about tests is that a test should perform two things: 1. Accept all conforming solutions @@ -335,59 +207,36 @@ The key thing about tests is that a test should perform two things: Some people might think that only point 1 is necessary, which is obviously untrue: test that accepts **everything** is pointless. Good tests will let the correct solutions -- *and only* the correct solutions -- pass. -For normal katas, a good set of tests should cover all of these aspects: +For normal kata, a good set of tests should cover all of these aspects: - Test basic functionality - Has full coverage (if that's impossible, at least have decent coverage) - Cover edge cases thoroughly - Randomized tests to probe user solution with random samples (and so that pattern-matching against the tests is impossible) - Stress/performance/code characteristic tests if needed -The first three should be put into fixed tests. The fourth item should be put into random tests. Ideally the last item would be in isolation, or covered by random tests. The last item is optional. - - -### An additional note on sample tests - -Sample tests are not required in general, but you should provide sample test cases. These are some basic test cases that users will see when they load the kata. - -You can include a few tests to get someone started, though of course if you're lazy you can just copy the fixed test cases from the actual tests over there. Just don't copy your reference solution there as well. - -Unless you intend the users to write tests themselves, or such is not applicable for your kata (Example: [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), it's usually considered a good practice to provide example test cases to the users. - - -### An additional note on random tests - -![(Source: [xkcd](https://xkcd.com/221/))](https://imgs.xkcd.com/comics/random_number.png) +The first three should be put into fixed tests. The fourth item should be put into random tests (see below). Ideally the last item would be in isolation, or covered by random tests. The last item is optional. Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for warriors to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. +Remember: just like in real life, if we failed a test, we want to know: +- what was the input +- expected and actual result -### Points that floats around - -If your test involves comparing two floating point numbers, note that due to the nature of floating point numbers, arithmetic expressions with the same result but expressed differently will generally incur tiny errors between them. Hence you should never ever check if they're equal. Instead, you should check if two numbers are equal by a tiny threshold. - -Some languages' test frameworks have the corresponding test functions to do this, e.g JavaScript's `Test.assertApproxEquals`. You should really [[consult the testing framework|Languages-and-Test-Frameworks]] for your language, or roll one yourself. The logic is roughly as: +So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of testing framework used by your [language](/languages/) and pick the best method for your tests. -``` -Suppose we already have the expected and actual value, and the threshold. +Writing good test suites is very difficult, often the most difficult part of creatign a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submssion tests](/authoring/guidelines/submission-tests/) when writing them. -if abs(expected) <= threshold: then we check abs(expected - actual) < threshold -else: we check abs((expected - actual) / expected) < threshold -(abs is the absolute value function). -``` -The threshold is usually around `1e-10` to `1e-12`, though depending on the situation at hand this can easily go up to `1e-4`, especially for numerical computation tasks. +#### Example Test Cases -### Test feedback +Example test cases is a small set of tests which user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. -Remember: just like in real life, if we failed a test, we want to know: -- what was the input -- expected and actual result +They are not necessary, but they are really good to have, so users can get the idea how the solution is called and tested.You can include a few tests to get someone started, though of course if you're lazy you can just copy the fixed test cases from the actual tests over there. Just don't copy your reference solution there as well. Unless you intend the users to write tests themselves, or tey are not applicable for your kata (Example: [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), it's usually considered a good practice to provide example test cases to the users. -So unless revealing the expected result would spoil the kata, you should not hide them. [[Consult the testing framework|Languages-and-Test-Frameworks]] and pick the best method for your tests. (Protip: `expect` is almost never the best pick.) +Since sample tests can significantly impact user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). -...Yes, who said writing tests are easy? Learning how to use the testing framework properly is part of learning how to code! _TODO: Announcing a kata and asking for feedback_ From 2fc2e4a0419f953808b533a13bf878bda00f08d1 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Fri, 8 Jan 2021 15:45:11 +0100 Subject: [PATCH 10/28] Fill in TODOs --- content/authoring/kata/create-first-kata.md | 34 +++++++++++++++++---- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 47ac3bcc..8569de1e 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -224,9 +224,7 @@ Remember: just like in real life, if we failed a test, we want to know: So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of testing framework used by your [language](/languages/) and pick the best method for your tests. -Writing good test suites is very difficult, often the most difficult part of creatign a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submssion tests](/authoring/guidelines/submission-tests/) when writing them. - - +Writing good test suites is very difficult, often the most difficult part of creatign a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submssion tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. #### Example Test Cases @@ -239,6 +237,30 @@ Since sample tests can significantly impact user experience of a kata, they have -_TODO: Announcing a kata and asking for feedback_ -_TODO: Responsibility and maintenance_ -_TODO: Common pitfalls_ \ No newline at end of file +## Before publishing + +When you have finally written all the code, prettified the description, and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, that it's very probable that you missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired. + +### Train on your kata + +Good first step is to train on your own kata. Getting in the shoes of a potential user is a nice way of checking what others will see and experience while training on your task. Although it's not possible to complete a kata being still in draft, it's still possible to train on it. Just open your kata in the trainer, and try to solve it, as any other user would do. This way, you can spot some problems with tests you have not thought about before. + +### Verify quality guidelines + +The next step would be to read through [authoring guidelines](/authoring/guidelines/) once again, and use them as a check-list to verify that your kata conforms to the applicable ones. Remember that the guidelines were collected basing on community's experience with many bad quality kata published back in the days, so take them seriously and approach them with proper attention. If you do not understand some guideline or you are not sure if your kata violates it or not, just ask more experienced users for advice. + +### Ask for a review of your draft + +Drafts of kata cannot be found and searched for, but can be accessed by other users with direct links. You can share the link to your not yet published kata with others, and they will be able to read the description, train on the kata, and provide some feedback, before getting a chance to downvote it. Sharing a link to a draft is a very good vay to get a quick feedback about the most obvious problems. + + +## After publishing + +After you publish your kata, it becomes a subject to the [beta evaluation](/concepts/kata/beta-process/). Power users immediately jump on it, knowing they _will_ find problems, the kata discussion section will be flooded with issue reports marked with red labels, and the red, sad faced button of "Not Satisfied" vote will cause the satisfaction rating drop to 20%. Unless there won't be any serious issues. It may be discouraging at first, especially for new authors, but when you think about it, it makes sense: after all, no one wants a bad kata to get out of beta, right? That's why it's important to make sure that when a kata is published, it's already in as good shape as possible. + +But still, no matter how hard you try, it's not possible to make everyone satisfied. Your kata may receive many satisfied votes, but even then, some users might not like it. Do not worry about this too much. Consider their remarks, and think a bit about them. Maybe they are right, and the kata needs some improvements? Listen to everyone, answer their questions, consider suggestions, and fix issues popping up. Also, do not rush things too much. If someone says something you are not sure about, just wait for another opinion. Users often do not agree with each other, so you can receive two mutually exclusive opinions. It can be difficult sometimes, but you just need to pass on one of them, or find some balance in between. Research shows \[citation needed] that kata with authors actively maintaining them leave beta quite quickly, while some kata can be retired within minutes, or, even worse, stay in beta forever, if authors do not want to fix problems. + +After the kata collects enough of positive feedback, it leaves beta state and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it in full extent. + + +Congratulations! Your first Codewars kata is a success! From 55c30827be987954fdf41d2e5d01c722cbb1b9d0 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Fri, 8 Jan 2021 16:20:12 +0100 Subject: [PATCH 11/28] Add note on required honor --- content/authoring/kata/create-first-kata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 8569de1e..e6b67db4 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -28,7 +28,7 @@ You can also reach directly to community to ask questions and seek for advice of ## Requirements -To create a new kata, you need to earn the ["Create Kata" privilege](/references/gamification/privileges/). After reaching the required amount of Honor, the privilege is granted and you can select the **"New Kata"** option from their profile menu: +To create a new kata, you need to earn the ["Create Kata" privilege](/references/gamification/privileges/). After reaching the required amount of 300 Honor points, the privilege is granted and you can select the **"New Kata"** option from their profile menu:
From 52561652b2f599a2bf3a486c5180ef0088093193 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 08:49:48 +0100 Subject: [PATCH 12/28] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/authoring/index.md | 4 ++-- content/authoring/kata/index.md | 4 ++-- content/authoring/translation/index.md | 4 ++-- content/references/ui/kata-editor/index.md | 3 +-- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/content/authoring/index.md b/content/authoring/index.md index f8e03aad..8a597fb0 100644 --- a/content/authoring/index.md +++ b/content/authoring/index.md @@ -5,9 +5,9 @@ next: /authoring/kata/ # Authoring of Codewars Content -All content available on Codewars is created by members of the Codewars community. It's ideas of Codewars users that get turned into kata, and only the fact that users are familiar with plenty of programming languages allows for a large number of available translations. +All content available on Codewars is created by members of the Codewars community. It's ideas of Codewars users that get turned into kata, and the fact that users are familiar with plenty of programming languages allows for a large number of available translations. -This section of the documentation is meant mostly for authors and translators, who would like to introduce new challenges and make them available for other Codewars users. Creating a kata or translating it, even an easy one, is a difficult task. It requires a much wider set of skills compared to the one required for just solving a kata. Unlike problem solvers, authors need to master skills related to software development in general, as well as to design of the problems, writing good test suites, documenting the task and its requirements, and communicating with reviewers. +This section of the documentation is meant mostly for authors and translators who would like to introduce new challenges and make them available for other Codewars users. Creating a kata or translating it, even an easy one, is a difficult task. It requires a much wider set of skills compared to that of just solving a kata. Unlike problem solvers, authors need to master skills related to software development in general, as well as problem design, writing good test suites, documenting the task and its requirements, and communicating with reviewers. To support users in creating good quality kata and translations, a set of help pages were created with articles related to content authoring activities: tutorials explaining how to create and translate a kata, and a reference of [guidelines][authoring-guidelines] and requirements that every author should follow to make sure that a piece of content created by them meets quality criteria. diff --git a/content/authoring/kata/index.md b/content/authoring/kata/index.md index 2e83f470..1e7e3f43 100644 --- a/content/authoring/kata/index.md +++ b/content/authoring/kata/index.md @@ -17,9 +17,9 @@ To create a new kata, a user needs to earn the ["Create Kata" privilege][referen Kata are created by filling the -Users new to creating kata can use [tutorial(TODO)](/authoring/kata/). +Users new to creating kata may refer to the [tutorial(TODO)](/authoring/kata/). -Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. +Some [languages](/languages/) also have a page dedicated to authoring kata, with code examples and best practices. Every kata author should follow [kata authoring guidelines](/authoring/guidelines/kata/). diff --git a/content/authoring/translation/index.md b/content/authoring/translation/index.md index 23e2844a..ec979eae 100644 --- a/content/authoring/translation/index.md +++ b/content/authoring/translation/index.md @@ -8,9 +8,9 @@ next: /authoring/guidelines/ _TBD: improve this stub_ -New translators can use [tutorial(TODO)](/authoring/translation/). +New translators may refer to the [tutorial(TODO)](/authoring/translation/). -Some [languages](/languages/) also have a page dedicated to creating a kata, with code examples and best practices. +Some [languages](/languages/) also have a page dedicated to authoring kata, with code examples and best practices. Every translator should follow [translation authoring guidelines](/authoring/guidelines/translation/). diff --git a/content/references/ui/kata-editor/index.md b/content/references/ui/kata-editor/index.md index bb15ddbe..d67568a0 100644 --- a/content/references/ui/kata-editor/index.md +++ b/content/references/ui/kata-editor/index.md @@ -13,5 +13,4 @@ next: /references/ui/kata-trainer/ ## What is the Kata Editor? -The Kata Editor is the authoring tool used to create and modify kata. It is accessible through the profile menu, found in the top right corner of this site. Only users who have earned the [[Create Kata|Privileges]] privilege. - +The Kata Editor is the authoring tool used to create and modify kata. It is accessible through the profile menu found in the top right corner of this site. Only users who have earned the [[Create Kata|Privileges]] privilege may access the Kata Editor. From b7028e82647d6c495872d4b7cb05edec77a720d0 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 08:59:18 +0100 Subject: [PATCH 13/28] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index e6b67db4..e6aac307 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -12,7 +12,7 @@ There is an obvious elephant in the room: Where do the katas come from? Obviousl Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. What authors sometimes do not realize is the fact that creating a good quality kata is much harder than solving it. -While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever, collecting negative feedback through the time. You don't want that. +While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever, collecting negative feedback over time. You don't want that. ## Support for authors From fe8ae2532dc89171f557e2d5591cd804857d86d7 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 09:02:19 +0100 Subject: [PATCH 14/28] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index e6aac307..ea6aee84 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -19,11 +19,11 @@ While a kata with minor problems can be easily fixed, a kata with fundamental is To support you with this difficult task, a set of help pages has been created with following types of information: - [tutorials](/tutorials/), for users who are still figuring things out, -- [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will meet with bad reception, harsh remarks, and many reported issues. +- [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will be met with bad reception, harsh remarks, and many reported issues. - [HOWTOs](/recipes/) explaining how to realize some commonly occuring tasks, or solve commonly repeating problems, - [Language specific pages](/languages/) with code snippets, examples, references and tutorials related to specific programming languages. -You can also reach directly to community to ask questions and seek for advice of experienced users on [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter chat. +You can also reach out directly to the community to ask questions and seek for advice of experienced users on the [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter channel. ## Requirements @@ -66,14 +66,14 @@ Then, maybe you can decide whether to retreat, or make a **harder** version of t #### Use a novel/original idea -If you find yourself worrying about hitting duplicates all the time, then try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas are hard! But if you can make sure your ideas are always novel and/or original, then you can be almost certain nobody will have taken the flag before you. +If you find yourself worrying about hitting duplicates all the time, try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas is hard! But if you can ensure that your ideas are always novel and original, you can be almost certain nobody will have taken the flag before you. It also has a side benefit of making people think that you're clever, which will be reflected on the [[satisfaction rating|Satisfaction Rating]]. -#### Solve more katas +#### Solve more kata -Naturally, when you've already solved 10 fibonacci katas, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) +Naturally, when you've already solved 10 fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) #### Solve more katas (again) From f076913f0a08e6f456d832051e40de22dd83cf53 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 09:05:49 +0100 Subject: [PATCH 15/28] Update content/authoring/kata/create-first-kata.md Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index ea6aee84..ee17eaef 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -84,7 +84,7 @@ Why? With just 300 honor, you haven't even get a grasp of what katas are actuall Anyone can reach 300 honor in a very short time, from a few hours to a day or two. This is, obviously, far from enough. Thus, you need to train more. -Solving more kata with more experiences can help one very significantly on these aspects: +Solving more kata to gain more experience can help one significantly in the following aspects: - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf katas: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) From e618511f96e123a2a71b890eefe83de7c3cefbe0 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 12:03:27 +0100 Subject: [PATCH 16/28] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index ee17eaef..68658259 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -80,7 +80,7 @@ Naturally, when you've already solved 10 fibonacci kata, solving another one wil While the minimum honor for creating a kata is merely 300 honor, if you try to create a kata with just 300 honor, it'll most likely inadvertently be bad. -Why? With just 300 honor, you haven't even get a grasp of what katas are actually like. +Why? With just 300 honor, you haven't even got a grasp of what kata are actually like. Anyone can reach 300 honor in a very short time, from a few hours to a day or two. This is, obviously, far from enough. Thus, you need to train more. @@ -88,18 +88,18 @@ Solving more kata to gain more experience can help one significantly in the foll - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf katas: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) -- Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from the history, and don't make the same mistake again! -- Looking at solutions (and more importantly, solution comment sections) will give you insight to what'd be good practice -- It also allows you to see how others write their tests. Writing good tests are **hard**, especially if your kata is also hard. +- Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! +- Looking at solutions (and more importantly, solution comment sections) will give you insight to what constitutes good practice +- It also allows you to see how others write their tests. Writing good tests is**hard**, especially if your kata is also hard. ## Stick to the intent, focus on one key thing per kata -If you ask people to do 10 katas about 10 different things, that's okay. +If you ask people to do 10 kata about 10 different things, that's okay. -But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 object at once is not fun. +But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 objects at once is not fun. -This often happens for unbalanced katas - while they're asking for doing one thing, because of how the kata is written the actual difficulty lies on something **completely unrelated** to the proposed intent of the kata itself, e.g doing a task with a very unnatural and hard to work with input format. +This often happens for unbalanced kata - while they're asking for one thing, because of how the kata is written the actual difficulty lies on something **completely unrelated** to the proposed intent of the kata itself, e.g doing a task with a very unnatural and hard to work with input format. If you find that your kata is too long, mostly from these symptoms: - your kata has a very long description @@ -108,7 +108,7 @@ If you find that your kata is too long, mostly from these symptoms: you might want to break up your kata in separate parts if appropriate. -Quoting power user @JohanWiltink's comment on one of the beta katas: +Quoting power user @JohanWiltink's comment on one of the beta kata: > And, again, you're doing multiple unrelated things in one kata. Totally unrelated, neither of them trivial this time. What is the intent, what is the pointe of this kata? > @@ -140,7 +140,7 @@ The discipline is the category that the kata belongs to. You should pick the cat #### Estimated rank -Here you specify how difficult you think your kata is. This value is used as an initial estimate for the kata difficulty, and will be refined while collecting rank votes from other users who solved it. Your perception on the difficulty of your katra might differ from what community might think and estimate, so your kata may end up finally accepted with higher or lower rank. +Here you specify how difficult you think your kata is. This value is used as an initial estimate for the kata difficulty, and will be refined while collecting rank votes from other users who solved it. Your perception on the difficulty of your kata might differ from what the community might think and estimate, so your kata may end up approved with a higher or lower rank. #### Tags @@ -175,7 +175,7 @@ To keep the kata easy to maintain, every snippet is a subject to quality guideli #### Complete Solution -You need to provide a solution to your own kata, to prove that it can be solved at all. Author's solution is run every time the kata is published, to verify correctness of tests and of general kata setup. +You need to provide a solution to your own kata, to prove that it can be solved at all. The author's solution is run every time the kata is published, to verify the correctness of tests and of the general kata setup. #### Initial Solution From 8610ad175467958efe275160dadd5bb4debbfb24 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 12:04:46 +0100 Subject: [PATCH 17/28] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 35 +++++++++++---------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 68658259..d52db1e0 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -179,7 +179,7 @@ You need to provide a solution to your own kata, to prove that it can be solved #### Initial Solution -Initial solution is what users are provided with when they start training on your kata. The way in which you setup your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include almost working or already fully working code within this block. For reference and algorithm disciplines you will likely only include skeleton code. Perhaps an empty function/method or some other code that has gaps which need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. +Initial solution is what users are provided with when they start training on your kata. The way in which you set up your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include an almost working or already fully working solution within this block. For fundamentals and algorithm disciplines you will likely only include skeleton code, such as an empty function/method or some other code that has gaps which need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. However, imagine the following scenario (assuming a statically typed language): you train on a Kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the Kata description and Sample Test Cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the Initial Solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? @@ -193,21 +193,23 @@ The initial solution block is required so you will have to include something (at The preloaded code block is an optional feature that you can use if you need it. The code from the preloaded snippet cannot be edited by the user, but it's available for all other snippets (solution and tests) to use. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example, it can contain classes or constants which should be common for both solution and tests. -Working with preloaded code is sometimes tricky, and that's why a set of [guidelines](/authoring/guidelines/preloaded/) related to this particular snipped is created. +Working with preloaded code is sometimes tricky, and that's why a set of [guidelines](/authoring/guidelines/preloaded/) related to this particular snipped has been created. #### Test Cases -The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them to consider the kata completed. Every language on Codewars is set up to provide you with a testing framework, which you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). +The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them for the kata to be considered completed. Every language on Codewars is set up to provide you with a testing framework which you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). While the old kata are usually lazy and only have a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. The key thing about tests is that a test should perform two things: + 1. Accept all conforming solutions -2. Reject all non-conforming solutions +1. Reject all non-conforming solutions -Some people might think that only point 1 is necessary, which is obviously untrue: test that accepts **everything** is pointless. Good tests will let the correct solutions -- *and only* the correct solutions -- pass. +Some people might think that only point 1 is necessary, but this is not true: tests that accept **everything** are pointless. Good tests will let *all* correct solutions -- and *only* correct solutions -- to pass. For normal kata, a good set of tests should cover all of these aspects: + - Test basic functionality - Has full coverage (if that's impossible, at least have decent coverage) - Cover edge cases thoroughly @@ -219,19 +221,20 @@ The first three should be put into fixed tests. The fourth item should be put in Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for warriors to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. Remember: just like in real life, if we failed a test, we want to know: -- what was the input -- expected and actual result + +- the input +- the expected and actual results So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of testing framework used by your [language](/languages/) and pick the best method for your tests. -Writing good test suites is very difficult, often the most difficult part of creatign a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submssion tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. +Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. #### Example Test Cases -Example test cases is a small set of tests which user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. +Example test cases is a small set of tests which the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. -They are not necessary, but they are really good to have, so users can get the idea how the solution is called and tested.You can include a few tests to get someone started, though of course if you're lazy you can just copy the fixed test cases from the actual tests over there. Just don't copy your reference solution there as well. Unless you intend the users to write tests themselves, or tey are not applicable for your kata (Example: [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), it's usually considered a good practice to provide example test cases to the users. +Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, though of course if you're lazy you can just copy over the fixed assertions in your submission tests to serve as the sample tests. Just remember *not* to copy your reference solution there as well. **It is a Kata issue if there are no sample tests** unless strong justification can be provided against them for a particular Kata. Since sample tests can significantly impact user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). @@ -239,28 +242,28 @@ Since sample tests can significantly impact user experience of a kata, they have ## Before publishing -When you have finally written all the code, prettified the description, and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, that it's very probable that you missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired. +When you have finally written all the code, prettified the description and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, it's very probable that you missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired. ### Train on your kata -Good first step is to train on your own kata. Getting in the shoes of a potential user is a nice way of checking what others will see and experience while training on your task. Although it's not possible to complete a kata being still in draft, it's still possible to train on it. Just open your kata in the trainer, and try to solve it, as any other user would do. This way, you can spot some problems with tests you have not thought about before. +A good first step is to train on your own kata. Getting in the shoes of a potential user is a nice way of checking what others will see and experience while training on your task. Although it's not possible to complete a kata being still in draft, it's still possible to train on it. Just open your kata in the trainer and try to solve it as any other user would do. This way, you can spot some problems with tests you may not have thought about before. ### Verify quality guidelines -The next step would be to read through [authoring guidelines](/authoring/guidelines/) once again, and use them as a check-list to verify that your kata conforms to the applicable ones. Remember that the guidelines were collected basing on community's experience with many bad quality kata published back in the days, so take them seriously and approach them with proper attention. If you do not understand some guideline or you are not sure if your kata violates it or not, just ask more experienced users for advice. +The next step would be to read through [authoring guidelines](/authoring/guidelines/) once again, and use them as a checklist to verify that your kata conforms to the applicable ones. Remember that the guidelines were collected based on the community's experience with many bad quality kata published back in the days, so take them seriously and approach them with proper attention. If you do not understand some guideline or you are not sure whether your kata violates it, just ask more experienced users for advice. ### Ask for a review of your draft -Drafts of kata cannot be found and searched for, but can be accessed by other users with direct links. You can share the link to your not yet published kata with others, and they will be able to read the description, train on the kata, and provide some feedback, before getting a chance to downvote it. Sharing a link to a draft is a very good vay to get a quick feedback about the most obvious problems. +Drafts of kata cannot be found and searched for, but can be accessed by other users with direct links. You can share the link to your not yet published kata with others, and they will be able to read the description, train on the kata, and provide some feedback, before getting a chance to downvote it. Sharing a link to a draft is a very good vay to get quick feedback about the most obvious problems. ## After publishing -After you publish your kata, it becomes a subject to the [beta evaluation](/concepts/kata/beta-process/). Power users immediately jump on it, knowing they _will_ find problems, the kata discussion section will be flooded with issue reports marked with red labels, and the red, sad faced button of "Not Satisfied" vote will cause the satisfaction rating drop to 20%. Unless there won't be any serious issues. It may be discouraging at first, especially for new authors, but when you think about it, it makes sense: after all, no one wants a bad kata to get out of beta, right? That's why it's important to make sure that when a kata is published, it's already in as good shape as possible. +After you publish your kata, it becomes subject to [beta evaluation](/concepts/kata/beta-process/). Power users immediately jump on it, knowing they _will_ find problems, the kata discussion section will be flooded with issue reports marked with red labels, and the red, sad faced button of the "Not Satisfied" vote will cause the satisfaction rating to drop to 20%. Unless there aren't any serious issues. It may be discouraging at first, especially for new authors, but when you think about it, it makes sense: after all, no one wants a bad kata to get out of beta, right? That's why it's important to make sure that when a kata is published, it's already in as good a shape as possible. But still, no matter how hard you try, it's not possible to make everyone satisfied. Your kata may receive many satisfied votes, but even then, some users might not like it. Do not worry about this too much. Consider their remarks, and think a bit about them. Maybe they are right, and the kata needs some improvements? Listen to everyone, answer their questions, consider suggestions, and fix issues popping up. Also, do not rush things too much. If someone says something you are not sure about, just wait for another opinion. Users often do not agree with each other, so you can receive two mutually exclusive opinions. It can be difficult sometimes, but you just need to pass on one of them, or find some balance in between. Research shows \[citation needed] that kata with authors actively maintaining them leave beta quite quickly, while some kata can be retired within minutes, or, even worse, stay in beta forever, if authors do not want to fix problems. -After the kata collects enough of positive feedback, it leaves beta state and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it in full extent. +After the kata collects enough positive feedback, it leaves the beta phase and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it in its full extent. Congratulations! Your first Codewars kata is a success! From 533b354c769743d8afb76f844c0013e57de99419 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 9 Jan 2021 12:08:31 +0100 Subject: [PATCH 18/28] Remarks from code review --- content/authoring/kata/create-first-kata.md | 2 +- content/authoring/kata/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index d52db1e0..b9f70c43 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -28,7 +28,7 @@ You can also reach out directly to the community to ask questions and seek for a ## Requirements -To create a new kata, you need to earn the ["Create Kata" privilege](/references/gamification/privileges/). After reaching the required amount of 300 Honor points, the privilege is granted and you can select the **"New Kata"** option from their profile menu: +To create a new kata, you need to earn the ["Create Kata" privilege](/references/gamification/privileges/). After reaching the required amount of 300 Honor points, the privilege is granted and you can select the **"New Kata"** option from the profile menu:
diff --git a/content/authoring/kata/index.md b/content/authoring/kata/index.md index 1e7e3f43..3095937f 100644 --- a/content/authoring/kata/index.md +++ b/content/authoring/kata/index.md @@ -15,7 +15,7 @@ To create a new kata, a user needs to earn the ["Create Kata" privilege][referen ## Kata Editor -Kata are created by filling the +Kata are created with the [kata editor](/references/ui/kata-editor/) Users new to creating kata may refer to the [tutorial(TODO)](/authoring/kata/). From 663e28d038fae5321e1564750ee8de993d2963d2 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 10 Jan 2021 14:16:54 +0100 Subject: [PATCH 19/28] Apply suggestions from code review Co-authored-by: Steffan <40404519+Steffan153@users.noreply.github.com> --- content/authoring/kata/create-first-kata.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index b9f70c43..4f892dbd 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -90,7 +90,7 @@ Solving more kata to gain more experience can help one significantly in the foll - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf katas: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) - Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! - Looking at solutions (and more importantly, solution comment sections) will give you insight to what constitutes good practice -- It also allows you to see how others write their tests. Writing good tests is**hard**, especially if your kata is also hard. +- It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. ## Stick to the intent, focus on one key thing per kata @@ -191,7 +191,7 @@ The initial solution block is required so you will have to include something (at #### Preloaded -The preloaded code block is an optional feature that you can use if you need it. The code from the preloaded snippet cannot be edited by the user, but it's available for all other snippets (solution and tests) to use. Its useful for when you want to load some code that mimics an API that your kata is based around. Its also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example, it can contain classes or constants which should be common for both solution and tests. +The preloaded code block is an optional feature that you can use if you need it. The code from the preloaded snippet cannot be edited by the user, but it's available for all other snippets (solution and tests) to use. It's useful for when you want to load some code that mimics an API that your kata is based around. It's also useful if you want to define some code that needs to be used within the solution, but shouldn't be editable within the solution itself. For example, it can contain classes or constants which should be common for both solution and tests. Working with preloaded code is sometimes tricky, and that's why a set of [guidelines](/authoring/guidelines/preloaded/) related to this particular snipped has been created. From 7bbe89d7dcd2a22ca33713afbdc5ec862ab8340b Mon Sep 17 00:00:00 2001 From: hobovsky Date: Mon, 11 Jan 2021 21:24:49 +0100 Subject: [PATCH 20/28] Apply suggestions from code review Co-authored-by: kazk --- content/authoring/kata/create-first-kata.md | 43 +++++++++------------ 1 file changed, 18 insertions(+), 25 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 4f892dbd..1ea146cc 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -6,9 +6,9 @@ sidebar: authoring # Creating your first kata -Okay, so you might have completed many (all?) of the published katas on Codewars. But... that's only half of the battle. +Okay, so you might have completed many (all?) of the published kata on Codewars. But... that's only half of the battle. -There is an obvious elephant in the room: Where do the katas come from? Obviously they didn't come out of nowhere like inside a stone or from a big bang, so clearly someone, or *something*, must have created the kata. +There is an obvious elephant in the room: Where do the kata come from? Obviously they didn't come out of nowhere like inside a stone or from a big bang, so clearly someone, or *something*, must have created the kata. Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. What authors sometimes do not realize is the fact that creating a good quality kata is much harder than solving it. @@ -45,12 +45,12 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references ## Kata Idea -At the time of writing, there are already **over 6500** published kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. +At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. -This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz katas out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. +This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. -### How to not step on the minefield of duplicate katas +### How to not step on the minefield of duplicate kata #### Search for keywords to see if someone has done the idea before @@ -59,7 +59,7 @@ As we all know, before you even engage your enemies, you need to send scouts for For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly shows, they've been done many times already. -In a way, knowing the katas in the wild is very similar to knowing your enemies: you get to see how others write the same kata, other people's (sometimes) brilliant solution in these katas. +In a way, knowing the kata in the wild is very similar to knowing your enemies: you get to see how others write the same kata, other people's (sometimes) brilliant solution in these kata. Then, maybe you can decide whether to retreat, or make a **harder** version of the kata as return if you feel the existing one is too lackluster/easy. @@ -68,7 +68,7 @@ Then, maybe you can decide whether to retreat, or make a **harder** version of t If you find yourself worrying about hitting duplicates all the time, try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas is hard! But if you can ensure that your ideas are always novel and original, you can be almost certain nobody will have taken the flag before you. -It also has a side benefit of making people think that you're clever, which will be reflected on the [[satisfaction rating|Satisfaction Rating]]. +It also has a side benefit of making people think that you're clever, which will be reflected on the satisfaction rating. #### Solve more kata @@ -76,7 +76,7 @@ It also has a side benefit of making people think that you're clever, which will Naturally, when you've already solved 10 fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) -#### Solve more katas (again) +#### Solve more kata (again) While the minimum honor for creating a kata is merely 300 honor, if you try to create a kata with just 300 honor, it'll most likely inadvertently be bad. @@ -87,7 +87,7 @@ Anyone can reach 300 honor in a very short time, from a few hours to a day or tw Solving more kata to gain more experience can help one significantly in the following aspects: - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. -- As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf katas: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) +- As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) - Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! - Looking at solutions (and more importantly, solution comment sections) will give you insight to what constitutes good practice - It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. @@ -108,12 +108,6 @@ If you find that your kata is too long, mostly from these symptoms: you might want to break up your kata in separate parts if appropriate. -Quoting power user @JohanWiltink's comment on one of the beta kata: - -> And, again, you're doing multiple unrelated things in one kata. Totally unrelated, neither of them trivial this time. What is the intent, what is the pointe of this kata? -> -> (Please note: a pointe is not a point. I'm not implying this kata is pointless. If anything, it seems overpointed - in width, not in depth.) - ## Setting up the kata @@ -129,7 +123,7 @@ The name is used to uniquely identify a kata. You can be creative with the name #### Discipline -The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are four categories: +The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are five categories: - Fundamentals - Focuses on core language and API knowledge. - Algorithms - Focuses on the logic required to complete the task. @@ -157,13 +151,13 @@ You can check the list of [privileges](/references/gamification/privileges/#priv ### Description -The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](https://docs.codewars.com/references/markdown/) with a set of [Codewars extensions](https://docs.codewars.com/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. +The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](/references/markdown/) with a set of [Codewars extensions](/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. -Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? Don't let yourself be the guy who wrote this. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your katas, and nobody will finish them at all. +Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? Don't let yourself be the one who wrote that. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your kata, and nobody will finish them at all. Fortunately, if your kata description is not very good, people will be eager to point this out in the comments, so you have more than enough chances to fix them. -Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](https://docs.codewars.com/authoring/guidelines/description/) to ensure that your description is of sufficient quality. +Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](/authoring/guidelines/description/) to ensure that your description is of sufficient quality. ### Code Snippets @@ -181,13 +175,12 @@ You need to provide a solution to your own kata, to prove that it can be solved Initial solution is what users are provided with when they start training on your kata. The way in which you set up your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include an almost working or already fully working solution within this block. For fundamentals and algorithm disciplines you will likely only include skeleton code, such as an empty function/method or some other code that has gaps which need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. -However, imagine the following scenario (assuming a statically typed language): you train on a Kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the Kata description and Sample Test Cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the Initial Solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? +However, imagine the following scenario (assuming a statically typed language): you train on a kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the kata description and the sample test cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the initial solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? -_Unless_ the focus of your Kata is debugging (and how often do you encounter debugging Kata that are even remotely enjoyable?) or your Kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the Initial Solution just to get it to compile. The Initial Solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that (s)he can start replacing the dummy implementations with his / her own code straight away. **It is a Kata issue if the Initial Solution fails to compile, especially if it introduces unnecessary overhead for the solver.** +_Unless_ the focus of your kata is debugging or your kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the initial solution just to get it to compile. The initial solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that they can start replacing the dummy implementations with their own code straight away. **It is a kata issue if the initial solution fails to compile, especially if it introduces unnecessary overhead for the solver.** -Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the Initial Solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. +Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the initial solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. -The initial solution block is required so you will have to include something (at the very least some comments) in order for the kata to be able to be published. #### Preloaded @@ -234,7 +227,7 @@ Writing good test suites is very difficult, often the most difficult part of cre Example test cases is a small set of tests which the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. -Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, though of course if you're lazy you can just copy over the fixed assertions in your submission tests to serve as the sample tests. Just remember *not* to copy your reference solution there as well. **It is a Kata issue if there are no sample tests** unless strong justification can be provided against them for a particular Kata. +Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, though of course if you're lazy you can just copy over the fixed assertions in your submission tests to serve as the sample tests. Just remember *not* to copy your reference solution there as well. **It is a kata issue if there are no sample tests** unless strong justification can be provided against them for a particular kata. Since sample tests can significantly impact user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). @@ -254,7 +247,7 @@ The next step would be to read through [authoring guidelines](/authoring/guideli ### Ask for a review of your draft -Drafts of kata cannot be found and searched for, but can be accessed by other users with direct links. You can share the link to your not yet published kata with others, and they will be able to read the description, train on the kata, and provide some feedback, before getting a chance to downvote it. Sharing a link to a draft is a very good vay to get quick feedback about the most obvious problems. +Drafts of kata cannot be found and searched for, but can be accessed by other users with direct links. You can share the link to your not yet published kata with others, and they will be able to read the description, train on the kata, and provide some feedback, before getting a chance to downvote it. Sharing a link to a draft is a very good way to get quick feedback about the most obvious problems. ## After publishing From 5ed130ff644d5d724f16428e7963337cdad9097d Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 16 Jan 2021 13:59:43 +0100 Subject: [PATCH 21/28] tone down the language a bit --- content/authoring/kata/create-first-kata.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 1ea146cc..6687dc78 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -6,13 +6,9 @@ sidebar: authoring # Creating your first kata -Okay, so you might have completed many (all?) of the published kata on Codewars. But... that's only half of the battle. +On Codewars, kata are created by regular users, who decided to share their idea with the community and create a task others could train on. People can come up with great ideas, and well crafted kara are source of great fun for everyone. After solving some kata, everyone sooner or later wants to contribute and create something others would enjoy to work on. Additionally, creating a kata can be a great learning experience. -There is an obvious elephant in the room: Where do the kata come from? Obviously they didn't come out of nowhere like inside a stone or from a big bang, so clearly someone, or *something*, must have created the kata. - -Creating a kata is a totally different kind of task from solving a kata. You might be able to solve a purple kata in under an hour, and still get flummoxed by the process of making a new kata. Being a good player doesn't always make you a good level maker, after all. What authors sometimes do not realize is the fact that creating a good quality kata is much harder than solving it. - -While a kata with minor problems can be easily fixed, a kata with fundamental issues will get stuck in the beta process forever, collecting negative feedback over time. You don't want that. +However, authors sometimes do not realize the fact that creating a good quality kata is much harder than solving it. Creating a kata is a totally different kind of task from solving a kata. It requires much wider mindset and set of skills. Creating a kata is much closer to "professional" tasks: it requires you to design a task with a large set of target users in mind, write a solution, create tests for it, handle feedback from users, and maintain it by fixing bugs. Every kata is a small software product in itself, and goes through a small equivalent of a full software development lifecycle! ## Support for authors @@ -153,9 +149,7 @@ You can check the list of [privileges](/references/gamification/privileges/#priv The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](/references/markdown/) with a set of [Codewars extensions](/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. -Have you encountered that feeling when you're met with a requirement you can't understand because it's poorly and inadequately written, and you still have to fulfill the requirement? Don't let yourself be the one who wrote that. If you ended up conjuring such hot garbage, everyone will just stay 10 miles away from you and your kata, and nobody will finish them at all. - -Fortunately, if your kata description is not very good, people will be eager to point this out in the comments, so you have more than enough chances to fix them. +Description of a kata is the first thing others see and decides on the user's first impression. If description is good, users will be probably encouraged took into the kata further. If description is bad, people won't hesitate to point this out, rising issues and downvoting your kata. Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](/authoring/guidelines/description/) to ensure that your description is of sufficient quality. @@ -192,7 +186,7 @@ Working with preloaded code is sometimes tricky, and that's why a set of [guidel The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them for the kata to be considered completed. Every language on Codewars is set up to provide you with a testing framework which you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). -While the old kata are usually lazy and only have a few tests, nowadays if you try to pull off the same trick you'll instantly get yelled at with all the `Needs random tests!!!!!11!1` and your satisfaction rating plummets to 0%. +Tests are very important aspect of every kata, and, after description, are probably the second factor determining its quality. Bad tests attract negative feedback and are a very common cause of auto-retirement for beta kata. Good tests, on the other hand, ore very appreciated by users training on your kata. Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. The key thing about tests is that a test should perform two things: @@ -211,7 +205,7 @@ For normal kata, a good set of tests should cover all of these aspects: The first three should be put into fixed tests. The fourth item should be put into random tests (see below). Ideally the last item would be in isolation, or covered by random tests. The last item is optional. -Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for warriors to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. +Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for users to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e. return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. Remember: just like in real life, if we failed a test, we want to know: @@ -220,14 +214,14 @@ Remember: just like in real life, if we failed a test, we want to know: So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of testing framework used by your [language](/languages/) and pick the best method for your tests. -Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution, and any flaws in the test suite can heavily impact the overall quality and experience of users with the kata. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. + #### Example Test Cases Example test cases is a small set of tests which the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. -Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, though of course if you're lazy you can just copy over the fixed assertions in your submission tests to serve as the sample tests. Just remember *not* to copy your reference solution there as well. **It is a kata issue if there are no sample tests** unless strong justification can be provided against them for a particular kata. +Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, and the easiest way is just to copy over the fixed tests tests from the full test suite to serve as the sample tests. **It is a kata issue if there are no sample tests** unless strong justification can be provided against them for a particular kata. Since sample tests can significantly impact user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). From a0af773aae3e790c305c3bf8c528ff9bcc479a31 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 16 Jan 2021 15:34:49 +0100 Subject: [PATCH 22/28] Apply suggestions from code review Co-authored-by: Steffan <40404519+Steffan153@users.noreply.github.com> --- content/authoring/kata/create-first-kata.md | 74 ++++++++++----------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 6687dc78..72bb74ff 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -6,20 +6,20 @@ sidebar: authoring # Creating your first kata -On Codewars, kata are created by regular users, who decided to share their idea with the community and create a task others could train on. People can come up with great ideas, and well crafted kara are source of great fun for everyone. After solving some kata, everyone sooner or later wants to contribute and create something others would enjoy to work on. Additionally, creating a kata can be a great learning experience. +On Codewars, kata are created by regular users, who decided to share their idea with the community and create a task others could train on. People can come up with great ideas, and well-crafted kata are a source of great fun for everyone. After solving some kata, everyone sooner or later wants to contribute and create something others would enjoy to work on. Additionally, creating a kata can be a great learning experience. -However, authors sometimes do not realize the fact that creating a good quality kata is much harder than solving it. Creating a kata is a totally different kind of task from solving a kata. It requires much wider mindset and set of skills. Creating a kata is much closer to "professional" tasks: it requires you to design a task with a large set of target users in mind, write a solution, create tests for it, handle feedback from users, and maintain it by fixing bugs. Every kata is a small software product in itself, and goes through a small equivalent of a full software development lifecycle! +However, authors sometimes do not realize the fact that creating a good quality kata is much harder than solving it. Creating kata is a totally different kind of task from solving kata. It requires a much wider mindset and set of skills. Creating a kata is much closer to "professional" tasks: it requires you to design a task with a large set of target users in mind, write a solution, create tests for it, handle feedback from users, and maintain it by fixing bugs. Every kata is a small software product in itself, and goes through a small equivalent of a full software development lifecycle! ## Support for authors -To support you with this difficult task, a set of help pages has been created with following types of information: +To support you with this difficult task, a set of help pages has been created with the following types of information: - [tutorials](/tutorials/), for users who are still figuring things out, - [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will be met with bad reception, harsh remarks, and many reported issues. -- [HOWTOs](/recipes/) explaining how to realize some commonly occuring tasks, or solve commonly repeating problems, -- [Language specific pages](/languages/) with code snippets, examples, references and tutorials related to specific programming languages. +- [HOWTOs](/recipes/) explaining how to realize some commonly occurring tasks, or solve commonly repeating problems, +- [Language specific pages](/languages/) with code snippets, examples, references, and tutorials related to specific programming languages. -You can also reach out directly to the community to ask questions and seek for advice of experienced users on the [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter channel. +You can also reach out directly to the community to ask questions and seek experienced users' advice on the [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter channel. ## Requirements @@ -41,7 +41,7 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references ## Kata Idea -At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. +At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers, or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. @@ -53,23 +53,23 @@ This is bad because creating a kata about them again constitutes a **duplicate** As we all know, before you even engage your enemies, you need to send scouts forward. -For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly shows, they've been done many times already. +For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly show, they've been done many times already. -In a way, knowing the kata in the wild is very similar to knowing your enemies: you get to see how others write the same kata, other people's (sometimes) brilliant solution in these kata. +In a way, knowing the kata in the wild is very similar to knowing your enemies: you get to see how others write the same kata and other people's (sometimes) brilliant solution in these kata. -Then, maybe you can decide whether to retreat, or make a **harder** version of the kata as return if you feel the existing one is too lackluster/easy. +Then, maybe you can decide whether to retreat or make a **harder** version of the kata as a fallback if you feel the existing one is too lackluster/easy. #### Use a novel/original idea If you find yourself worrying about hitting duplicates all the time, try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas is hard! But if you can ensure that your ideas are always novel and original, you can be almost certain nobody will have taken the flag before you. -It also has a side benefit of making people think that you're clever, which will be reflected on the satisfaction rating. +It also has a side benefit of making people think that you're clever, which will be reflected in the satisfaction rating. #### Solve more kata -Naturally, when you've already solved 10 fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) +Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) #### Solve more kata (again) @@ -84,8 +84,8 @@ Solving more kata to gain more experience can help one significantly in the foll - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) -- Actually encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! -- Looking at solutions (and more importantly, solution comment sections) will give you insight to what constitutes good practice +- Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! +- Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. - It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. @@ -102,35 +102,35 @@ If you find that your kata is too long, mostly from these symptoms: - a typical solution is very long and yet none of them is hard, the only difficulty is from the tediousness - your kata requires doing many things together, -you might want to break up your kata in separate parts if appropriate. +you might want to break up your kata into separate parts if appropriate. ## Setting up the kata -Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/). To fully set up the kata you have to provide some basic information, as well as write some code in language(s) of your choice. +Kata are edited with the kata editor tool, described in the [Kata Editor UI reference](/references/ui/kata-editor/). To fully set up the kata you have to provide some basic information, as well as write some code in the language(s) of your choice. ### Kata Properties #### Name -The name is used to uniquely identify a kata. You can be creative with the name that you use. Best practice is to use a name that gives other users a good idea of what type of challenge they will be getting themselves into. +The name is used to uniquely identify a kata. You can be creative with the name that you use. The best practice is to use a name that gives other users a good idea of what type of challenge they will be getting themselves into. #### Discipline -The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now there are five categories: +The discipline is the category that the kata belongs to. You should pick the category that best describes what the kata is intended to focus on. As of now, there are five categories: -- Fundamentals - Focuses on core language and API knowledge. +- Fundamentals - Focuses on the core language and API knowledge. - Algorithms - Focuses on the logic required to complete the task. -- Bug Fixes - Focuses on taking existing code, determining the issue and fixing it. +- Bug Fixes - Focuses on taking existing code, determining the issue, and fixing it. - Refactoring - Focuses on taking existing code and making it better. - Puzzles #### Estimated rank -Here you specify how difficult you think your kata is. This value is used as an initial estimate for the kata difficulty, and will be refined while collecting rank votes from other users who solved it. Your perception on the difficulty of your kata might differ from what the community might think and estimate, so your kata may end up approved with a higher or lower rank. +Here you specify how difficult you think your kata is. This value is used as an initial estimate for the kata difficulty and will be refined while collecting rank votes from other users who solved it. Your perception of the difficulty of your kata might differ from what the community might think and estimate, so your kata may end up approved with a higher or lower rank. #### Tags @@ -158,22 +158,22 @@ Writing good descriptions is a difficult task, and you should refer to ["Writing To make your kata runnable, you need to write some code. Kata code is divided into a couple of snippets, each of them having a specific role, and being used in specific circumstances. -To keep the kata easy to maintain, every snippet is a subject to quality guidelines, both [general](/authoring/guidelines/coding/), and a set specific for each of them. +To keep the kata easy to maintain, every snippet is subject to quality guidelines, both [general](/authoring/guidelines/coding/), and a set specific for each of them. #### Complete Solution -You need to provide a solution to your own kata, to prove that it can be solved at all. The author's solution is run every time the kata is published, to verify the correctness of tests and of the general kata setup. +You need to provide a solution to your own kata, to prove that it can be solved at all. The author's solution is run every time the kata is published, to verify the correctness of tests and the general kata setup. #### Initial Solution -Initial solution is what users are provided with when they start training on your kata. The way in which you set up your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include an almost working or already fully working solution within this block. For fundamentals and algorithm disciplines you will likely only include skeleton code, such as an empty function/method or some other code that has gaps which need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. +The initial solution is what users are provided with when they start training on your kata. How you set up your initial solution code will depend heavily on the discipline that you have selected. For bug and refactor disciplines you will end up needing to include an almost working or already fully working solution within this block. For fundamentals and algorithm disciplines you will likely only include skeleton code, such as an empty function/method or some other code that has gaps that need to be filled in. Sometimes you may just want to include some comments to help get the user started, but no actual code. However, imagine the following scenario (assuming a statically typed language): you train on a kata that requires you to implement multiple functions, but the Initial Solution does not give you the relevant function signatures and hence fails to compile. You frantically read through the kata description and the sample test cases to figure out the function signatures you need to add: the name of each function, the number of arguments to each function, the type of each argument, the return type of the function ... After fumbling with the initial solution for a full 15 minutes, you finally get it to compile. _Now_ you can actually focus on the task at hand. Not cool, right? _Unless_ the focus of your kata is debugging or your kata involves some deep C++ compile-time metaprogramming where 50% of the challenge itself is to make the code compile, you most certainly do not want the solver to waste their precious time fixing the initial solution just to get it to compile. The initial solution should provide the solver with a dummy implementation that "works" out of the box (possibly with runtime errors) such that they can start replacing the dummy implementations with their own code straight away. **It is a kata issue if the initial solution fails to compile, especially if it introduces unnecessary overhead for the solver.** -Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the initial solution should not contain syntax errors and / or (top-level) reference errors which may prevent the solver from getting started with the task immediately. +Note that similar principles apply to interpreted languages (e.g. JavaScript, Python, Ruby): the initial solution should not contain syntax errors and/or (top-level) reference errors which may prevent the solver from getting started with the task immediately. #### Preloaded @@ -184,9 +184,9 @@ Working with preloaded code is sometimes tricky, and that's why a set of [guidel #### Test Cases -The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them for the kata to be considered completed. Every language on Codewars is set up to provide you with a testing framework which you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). +The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them for the kata to be considered complete. Every language on Codewars is set up to provide you with a testing framework that you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). -Tests are very important aspect of every kata, and, after description, are probably the second factor determining its quality. Bad tests attract negative feedback and are a very common cause of auto-retirement for beta kata. Good tests, on the other hand, ore very appreciated by users training on your kata. Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting for inexperienced authors. +Tests are a very important aspect of every kata, and, after description, are probably the second factor determining its quality. Bad tests attract negative feedback and are a very common cause of auto-retirement for beta kata. Good tests, on the other hand, are very appreciated by users training on your kata. Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting inexperienced authors. The key thing about tests is that a test should perform two things: @@ -195,7 +195,7 @@ The key thing about tests is that a test should perform two things: Some people might think that only point 1 is necessary, but this is not true: tests that accept **everything** are pointless. Good tests will let *all* correct solutions -- and *only* correct solutions -- to pass. -For normal kata, a good set of tests should cover all of these aspects: +For a normal kata, a good set of tests should cover all of these aspects: - Test basic functionality - Has full coverage (if that's impossible, at least have decent coverage) @@ -203,33 +203,33 @@ For normal kata, a good set of tests should cover all of these aspects: - Randomized tests to probe user solution with random samples (and so that pattern-matching against the tests is impossible) - Stress/performance/code characteristic tests if needed -The first three should be put into fixed tests. The fourth item should be put into random tests (see below). Ideally the last item would be in isolation, or covered by random tests. The last item is optional. +The first three should be put into fixed tests. The fourth item should be put into random tests (see below). Ideally, the last item would be in isolation or covered by random tests. The last item is optional. -Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases with make it both easy for users to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e. return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. +Random test cases are test cases that cannot be predicted. Most kata have them (except for the really old ones) and they are usually in addition to some static tests. Using both static and random test cases make it both easy for users to see what they are supposed to do, as well as make it impossible to write a solution that just pattern match the inputs (i.e. return hard-coded outputs depending on a fixed set of inputs). Random tests are also good at finding edge cases. Remember: just like in real life, if we failed a test, we want to know: - the input - the expected and actual results -So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of testing framework used by your [language](/languages/) and pick the best method for your tests. +So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of the testing framework used by your [language](/languages/) and pick the best method for your tests. #### Example Test Cases -Example test cases is a small set of tests which the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. +Example test cases are a small set of tests that the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. -Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, and the easiest way is just to copy over the fixed tests tests from the full test suite to serve as the sample tests. **It is a kata issue if there are no sample tests** unless strong justification can be provided against them for a particular kata. +Except in circumstances where providing sample tests to the user would spoil the kata (such as [Defuse the bombs](https://www.codewars.com/kata/defuse-the-bombs/)), they are absolutely **required** as users can get an idea of how the solution is called and tested. You should include a few tests to get someone started, and the easiest way is just to copy over the fixed tests from the full test suite to serve as the sample tests. **It is a kata issue if there are no sample tests** unless strong justification can be provided against them for a particular kata. -Since sample tests can significantly impact user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). +Since sample tests can significantly impact the user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). ## Before publishing -When you have finally written all the code, prettified the description and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, it's very probable that you missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired. +When you have finally written all the code, prettified the description, and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, you probably missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired. ### Train on your kata @@ -246,11 +246,11 @@ Drafts of kata cannot be found and searched for, but can be accessed by other us ## After publishing -After you publish your kata, it becomes subject to [beta evaluation](/concepts/kata/beta-process/). Power users immediately jump on it, knowing they _will_ find problems, the kata discussion section will be flooded with issue reports marked with red labels, and the red, sad faced button of the "Not Satisfied" vote will cause the satisfaction rating to drop to 20%. Unless there aren't any serious issues. It may be discouraging at first, especially for new authors, but when you think about it, it makes sense: after all, no one wants a bad kata to get out of beta, right? That's why it's important to make sure that when a kata is published, it's already in as good a shape as possible. +After you publish your kata, it becomes subject to [beta evaluation](/concepts/kata/beta-process/). Power users immediately jump on it, knowing they _will_ find problems, the kata discussion section will be flooded with issue reports marked with red labels, and the red, sad-faced button of the "Not Satisfied" vote will cause the satisfaction rating to drop to 20%. Unless there aren't any serious issues. It may be discouraging at first, especially for new authors, but when you think about it, it makes sense: after all, no one wants a bad kata to get out of beta, right? That's why it's important to make sure that when a kata is published, it's already in as good a shape as possible. But still, no matter how hard you try, it's not possible to make everyone satisfied. Your kata may receive many satisfied votes, but even then, some users might not like it. Do not worry about this too much. Consider their remarks, and think a bit about them. Maybe they are right, and the kata needs some improvements? Listen to everyone, answer their questions, consider suggestions, and fix issues popping up. Also, do not rush things too much. If someone says something you are not sure about, just wait for another opinion. Users often do not agree with each other, so you can receive two mutually exclusive opinions. It can be difficult sometimes, but you just need to pass on one of them, or find some balance in between. Research shows \[citation needed] that kata with authors actively maintaining them leave beta quite quickly, while some kata can be retired within minutes, or, even worse, stay in beta forever, if authors do not want to fix problems. -After the kata collects enough positive feedback, it leaves the beta phase and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it in its full extent. +After the kata collects enough positive feedback, it leaves the beta phase and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it to its full extent. Congratulations! Your first Codewars kata is a success! From e61992c4cabef0c9c3514d70a2e958e61df93d03 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 17 Jan 2021 12:01:33 +0100 Subject: [PATCH 23/28] Apply suggestions from code review Co-authored-by: kazk Co-authored-by: Steffan <40404519+Steffan153@users.noreply.github.com> Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 72bb74ff..ba5ee094 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -46,7 +46,7 @@ At the time of writing, there are already **over 6500** approved kata, and almos This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. -### How to not step on the minefield of duplicate kata +### How to avoid creating a duplicate kata #### Search for keywords to see if someone has done the idea before @@ -149,7 +149,7 @@ You can check the list of [privileges](/references/gamification/privileges/#priv The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](/references/markdown/) with a set of [Codewars extensions](/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. -Description of a kata is the first thing others see and decides on the user's first impression. If description is good, users will be probably encouraged took into the kata further. If description is bad, people won't hesitate to point this out, rising issues and downvoting your kata. +The description of a kata is the first thing others see and decides on the user's first impression. If the description is good, users will be probably encouraged to take the kata further. If the description is bad, people won't hesitate to point this out, rising issues and downvoting your kata. Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](/authoring/guidelines/description/) to ensure that your description is of sufficient quality. @@ -186,7 +186,7 @@ Working with preloaded code is sometimes tricky, and that's why a set of [guidel The **Test Cases** editor is used to write submission tests: code that will validate the kata solution. Tests are not visible to the user, and the user solution needs to pass them for the kata to be considered complete. Every language on Codewars is set up to provide you with a testing framework that you can use to write test cases, organize them into groups, and assert on tested conditions. You can find out what testing framework you need to use by visiting the [reference page of your language](/languages/). -Tests are a very important aspect of every kata, and, after description, are probably the second factor determining its quality. Bad tests attract negative feedback and are a very common cause of auto-retirement for beta kata. Good tests, on the other hand, are very appreciated by users training on your kata. Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you to avoid many common pitfalls awaiting inexperienced authors. +Tests are a very important aspect of every kata, and, after the description, are probably the second factor determining its quality. Bad tests attract negative feedback and are a very common cause of auto-retirement for beta kata. Good tests, on the other hand, are highly appreciated by users training on your kata. Writing good test suites is very difficult, often the most difficult part of creating a kata. It often requires more code than the actual solution. Make sure you follow [quality guidelines for submission tests](/authoring/guidelines/submission-tests/) when writing them, as they will help you avoid many common pitfalls awaiting inexperienced authors. The key thing about tests is that a test should perform two things: From 053e61209e0290c1613614ec467211e56fc7cd5a Mon Sep 17 00:00:00 2001 From: hobovsky Date: Fri, 22 Jan 2021 22:11:56 +0100 Subject: [PATCH 24/28] Apply suggestions from code review Co-authored-by: kazk Co-authored-by: Donald Sebastian Leung --- content/authoring/kata/create-first-kata.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index ba5ee094..46711cd8 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -60,11 +60,6 @@ In a way, knowing the kata in the wild is very similar to knowing your enemies: Then, maybe you can decide whether to retreat or make a **harder** version of the kata as a fallback if you feel the existing one is too lackluster/easy. -#### Use a novel/original idea - -If you find yourself worrying about hitting duplicates all the time, try to push yourself to think out-of-the-box. Don't worry, coming up with good ideas is hard! But if you can ensure that your ideas are always novel and original, you can be almost certain nobody will have taken the flag before you. - -It also has a side benefit of making people think that you're clever, which will be reflected in the satisfaction rating. #### Solve more kata @@ -149,7 +144,7 @@ You can check the list of [privileges](/references/gamification/privileges/#priv The description field is used to provide instructions to the users who will be training on the kata. This field recognizes [Github flavored markdown](/references/markdown/) with a set of [Codewars extensions](/references/markdown/extensions/). You can use the `Preview` tab to see how it will look like when presented to users. -The description of a kata is the first thing others see and decides on the user's first impression. If the description is good, users will be probably encouraged to take the kata further. If the description is bad, people won't hesitate to point this out, rising issues and downvoting your kata. +The description of a kata is the first thing others see and forms the basis of users' first impressions. If the description is good, users will probably be encouraged to take the kata further. Otherwise, people won't hesitate to raise issues and downvote your kata. Writing good descriptions is a difficult task, and you should refer to ["Writing a Kata Description" guidelines](/authoring/guidelines/description/) to ensure that your description is of sufficient quality. From 4b51ea99cb64dead31f861d07eba58ef53935a77 Mon Sep 17 00:00:00 2001 From: Donald Sebastian Leung Date: Sat, 23 Jan 2021 13:58:14 +0800 Subject: [PATCH 25/28] Apply suggestions from code review Co-authored-by: Steffan <40404519+Steffan153@users.noreply.github.com> --- content/authoring/kata/create-first-kata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 46711cd8..c0aa9304 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -57,7 +57,7 @@ For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [C In a way, knowing the kata in the wild is very similar to knowing your enemies: you get to see how others write the same kata and other people's (sometimes) brilliant solution in these kata. -Then, maybe you can decide whether to retreat or make a **harder** version of the kata as a fallback if you feel the existing one is too lackluster/easy. +Then, maybe you can decide whether to retreat or make a **harder** version of the kata in return if you feel the existing one is too lackluster/easy. From dabd3fa8574244bfb218796b7ebee2f1278c8670 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 20 Feb 2021 13:18:19 +0100 Subject: [PATCH 26/28] Redo 'avoid duplicates'; hold back with approving translations --- content/authoring/kata/create-first-kata.md | 50 +++++++-------------- 1 file changed, 16 insertions(+), 34 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index c0aa9304..6d4d9149 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -41,7 +41,7 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references ## Kata Idea -At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers, or Caesar/ROT cipher, it's pretty much `99.999999...%` chance that someone has done this before you. +At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers, or Caesar/ROT cipher, it's pretty much 99.999999...% chance that someone has done this before you. This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. @@ -49,39 +49,19 @@ This is bad because creating a kata about them again constitutes a **duplicate** ### How to avoid creating a duplicate kata -#### Search for keywords to see if someone has done the idea before - -As we all know, before you even engage your enemies, you need to send scouts forward. - -For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly show, they've been done many times already. - -In a way, knowing the kata in the wild is very similar to knowing your enemies: you get to see how others write the same kata and other people's (sometimes) brilliant solution in these kata. - -Then, maybe you can decide whether to retreat or make a **harder** version of the kata in return if you feel the existing one is too lackluster/easy. - - - - -#### Solve more kata - -Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) - - -#### Solve more kata (again) - -While the minimum honor for creating a kata is merely 300 honor, if you try to create a kata with just 300 honor, it'll most likely inadvertently be bad. - -Why? With just 300 honor, you haven't even got a grasp of what kata are actually like. - -Anyone can reach 300 honor in a very short time, from a few hours to a day or two. This is, obviously, far from enough. Thus, you need to train more. - -Solving more kata to gain more experience can help one significantly in the following aspects: - -- Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. -- As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) -- Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! -- Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. -- It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. +- Try hard to **come up with some novel and original idea.** It would mean not only creating some original theme or backstory, but the task should also ideally boil down to some new, interesting approach. There's already many kata which can be brought down to one of a very popular ideas: + - Topics common when learnign programming. Fibonacci, fizz-buzz, factorial, there's already plenty of them. + - Simple map/filter/reduce operations on a list or array. There's too many kata which require just to iterate over a sequence and pick/reject/transform some of its elements based on some simple criteria. + - Calculating a result of a formula, be it mathematical, physical, or chemical. Substituting values into a formula has been done many times. + - Simple graph search. Patch finding, simple BFS, DFS, there's already [enough kata](https://www.codewars.com/collections/bfs-shitpost) to make it boring. +- **[Search for keywords](https://www.codewars.com/kata/search/?q=&) to see if someone has done the idea before.** Many topics has been already extensively covered. There are many kata related to [Fibonacci numbers](https://www.codewars.com/kata/search/?q=fibonacci&), [factorials](https://www.codewars.com/kata/search/?q=factorial&&order_by=rank_id%20asc), [fizz-buzz](https://www.codewars.com/kata/search/?q=buzz&&order_by=rank_id%20asc), and other common topics. Even some very advanced topics have many similar kata. For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly show, they've been done many times already. +- **Solve more kata.** This way you will get better feeling of what is already there and what topics appear often in search results.Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) Additionally, you will gain more experience with the platform, users, their opinions, and what they actually expect. Solving more kata to gain more experience can help one significantly in the following aspects: + - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. + - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) + - Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! + - Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. + - It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. +- **Solve and review beta kata.** This way you can learn a lot from mistakes of others and see what are the most common ideas and mistakes of kata authors, how reviewers react to them, and what are possible ways to resolve them. ## Stick to the intent, focus on one key thing per kata @@ -245,6 +225,8 @@ After you publish your kata, it becomes subject to [beta evaluation](/concepts/k But still, no matter how hard you try, it's not possible to make everyone satisfied. Your kata may receive many satisfied votes, but even then, some users might not like it. Do not worry about this too much. Consider their remarks, and think a bit about them. Maybe they are right, and the kata needs some improvements? Listen to everyone, answer their questions, consider suggestions, and fix issues popping up. Also, do not rush things too much. If someone says something you are not sure about, just wait for another opinion. Users often do not agree with each other, so you can receive two mutually exclusive opinions. It can be difficult sometimes, but you just need to pass on one of them, or find some balance in between. Research shows \[citation needed] that kata with authors actively maintaining them leave beta quite quickly, while some kata can be retired within minutes, or, even worse, stay in beta forever, if authors do not want to fix problems. +After your kata gets published and it gains a couple of solutions, it's very probable that someone will translate it to some other language for you. This is great, but do not get excited about this. It's _recommended_ to hold back with approving new translations until the original version settles down, gets all isues resolved, and the kata matures a bit. When someone reports some design issue with your kata and it needs to be changed in some way, approved translations can make it difficult and they become additional maintenance effort. High maintenance cost is something you want to avoid at the early stage of a kata, when it's expected to change a lot. + After the kata collects enough positive feedback, it leaves the beta phase and becomes available for everyone to train on and earn their points. Now it will draw even more attention, and potentially thousands of users will submit their solutions, possibly finding new problems reporting new issues, and raising new suggestions. Your task, as an author, is to actively maintain the kata. This will encourage others to train on it more, provide translations to other languages, and enjoy it to its full extent. From fa9df81f6488d4935df65e6340766a77bf824e42 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 20 Feb 2021 13:30:53 +0100 Subject: [PATCH 27/28] formatting --- content/authoring/kata/create-first-kata.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 6d4d9149..95420412 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -14,9 +14,9 @@ However, authors sometimes do not realize the fact that creating a good quality ## Support for authors To support you with this difficult task, a set of help pages has been created with the following types of information: -- [tutorials](/tutorials/), for users who are still figuring things out, -- [guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will be met with bad reception, harsh remarks, and many reported issues. -- [HOWTOs](/recipes/) explaining how to realize some commonly occurring tasks, or solve commonly repeating problems, +- [Tutorials](/tutorials/), for users who are still figuring things out. +- [Guidelines](/authoring/guidelines/), which need to be respected to meet the Codewars quality criteria. It is strongly recommended to become familiar with these, otherwise you risk that your kata will be met with bad reception, harsh remarks, and many reported issues. +- [HOWTOs](/recipes/) explaining how to realize some commonly occurring tasks, or solve commonly repeating problems. - [Language specific pages](/languages/) with code snippets, examples, references, and tutorials related to specific programming languages. You can also reach out directly to the community to ask questions and seek experienced users' advice on the [kata-authoring-help](https://gitter.im/Codewars/codewars.com/kata-authoring-help) Gitter channel. @@ -48,20 +48,19 @@ This is bad because creating a kata about them again constitutes a **duplicate** ### How to avoid creating a duplicate kata - -- Try hard to **come up with some novel and original idea.** It would mean not only creating some original theme or backstory, but the task should also ideally boil down to some new, interesting approach. There's already many kata which can be brought down to one of a very popular ideas: +- Try hard to **come up with some novel and original idea.** It would mean not only creating some original theme or backstory, but the task should also ideally boil down to some new, interesting approach. There's already many kata which can be brought down to one of very popular ideas: - Topics common when learnign programming. Fibonacci, fizz-buzz, factorial, there's already plenty of them. - Simple map/filter/reduce operations on a list or array. There's too many kata which require just to iterate over a sequence and pick/reject/transform some of its elements based on some simple criteria. - Calculating a result of a formula, be it mathematical, physical, or chemical. Substituting values into a formula has been done many times. - Simple graph search. Patch finding, simple BFS, DFS, there's already [enough kata](https://www.codewars.com/collections/bfs-shitpost) to make it boring. - **[Search for keywords](https://www.codewars.com/kata/search/?q=&) to see if someone has done the idea before.** Many topics has been already extensively covered. There are many kata related to [Fibonacci numbers](https://www.codewars.com/kata/search/?q=fibonacci&), [factorials](https://www.codewars.com/kata/search/?q=factorial&&order_by=rank_id%20asc), [fizz-buzz](https://www.codewars.com/kata/search/?q=buzz&&order_by=rank_id%20asc), and other common topics. Even some very advanced topics have many similar kata. For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly show, they've been done many times already. -- **Solve more kata.** This way you will get better feeling of what is already there and what topics appear often in search results.Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) Additionally, you will gain more experience with the platform, users, their opinions, and what they actually expect. Solving more kata to gain more experience can help one significantly in the following aspects: +- **Solve more kata.** This way you will get better feeling of what is already there and what topics appear often in search results. Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) Additionally, you will gain more experience with the platform, users, their opinions, and what they actually expect. Solving more kata to gain more experience can help one significantly in the following aspects: - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) - Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! - Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. - It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. -- **Solve and review beta kata.** This way you can learn a lot from mistakes of others and see what are the most common ideas and mistakes of kata authors, how reviewers react to them, and what are possible ways to resolve them. +- **Solve and review [beta kata](https://www.codewars.com/kata/search/my-languages?q=&&xids=completed&beta=true).** This way you can learn a lot from mistakes of others and see what are the most common ideas and mistakes of kata authors, how reviewers react to them, and what are possible ways to resolve them. ## Stick to the intent, focus on one key thing per kata From 9fce20f69ed029b7e54b2bd767e4c909e328f61a Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sat, 20 Feb 2021 14:15:50 +0100 Subject: [PATCH 28/28] organization --- content/authoring/kata/create-first-kata.md | 45 +++++++++------------ 1 file changed, 20 insertions(+), 25 deletions(-) diff --git a/content/authoring/kata/create-first-kata.md b/content/authoring/kata/create-first-kata.md index 95420412..d3e27198 100644 --- a/content/authoring/kata/create-first-kata.md +++ b/content/authoring/kata/create-first-kata.md @@ -38,45 +38,43 @@ To create a new kata, you need to earn the ["Create Kata" privilege](/references
+## How to make a good kata? -## Kata Idea +Everyone enjoys good, wellcrafted kata, and no one likes to struggle with poorly authored challenges. However, especially for unexperienced authors, it's often difficult to tell what is good, what is bad, or why. There's a few aspects which can drastically influence experience of other users with your kata and, as a result, feedback it will receive. -At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers, or Caesar/ROT cipher, it's pretty much 99.999999...% chance that someone has done this before you. -This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. +### Kata Idea and Duplicates +At the time of writing, there are already **over 6500** approved kata, and almost 2500 beta kata. It's a vast red ocean out there - if you're still sticking to ideas like Fizzbuzz, Fibonacci numbers, or Caesar/ROT cipher, it's pretty much 99.999999...% chance that someone has done this before you. -### How to avoid creating a duplicate kata +This is bad because creating a kata about them again constitutes a **duplicate** kata, and we certainly don't want 100 Fizzbuzz kata out in the wild. When a duplicate is found it will be retired, which basically means it gets taken out of the kata catalog. -- Try hard to **come up with some novel and original idea.** It would mean not only creating some original theme or backstory, but the task should also ideally boil down to some new, interesting approach. There's already many kata which can be brought down to one of very popular ideas: +To make sure users will like the idea presented in your kata, you can: +- Try to **come up with some novel and original idea.** It would mean not only creating some original theme or backstory, but the task should also ideally boil down to some new, interesting approach. There's already many kata which can be brought down to one of very popular ideas: - Topics common when learnign programming. Fibonacci, fizz-buzz, factorial, there's already plenty of them. - Simple map/filter/reduce operations on a list or array. There's too many kata which require just to iterate over a sequence and pick/reject/transform some of its elements based on some simple criteria. - Calculating a result of a formula, be it mathematical, physical, or chemical. Substituting values into a formula has been done many times. - - Simple graph search. Patch finding, simple BFS, DFS, there's already [enough kata](https://www.codewars.com/collections/bfs-shitpost) to make it boring. + - Simple graph search. Simple patch finding, BFS, DFS, there's already [enough kata](https://www.codewars.com/collections/bfs-shitpost) to make it boring. - **[Search for keywords](https://www.codewars.com/kata/search/?q=&) to see if someone has done the idea before.** Many topics has been already extensively covered. There are many kata related to [Fibonacci numbers](https://www.codewars.com/kata/search/?q=fibonacci&), [factorials](https://www.codewars.com/kata/search/?q=factorial&&order_by=rank_id%20asc), [fizz-buzz](https://www.codewars.com/kata/search/?q=buzz&&order_by=rank_id%20asc), and other common topics. Even some very advanced topics have many similar kata. For example, while [Peano](https://www.codewars.com/kata/search/?q=peano) and [Church](https://www.codewars.com/kata/search/?q=church) numbers are definitely not easy, as the search results clearly show, they've been done many times already. -- **Solve more kata.** This way you will get better feeling of what is already there and what topics appear often in search results. Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) Additionally, you will gain more experience with the platform, users, their opinions, and what they actually expect. Solving more kata to gain more experience can help one significantly in the following aspects: - - Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. - - As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) - - Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! - - Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. - - It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. -- **Solve and review [beta kata](https://www.codewars.com/kata/search/my-languages?q=&&xids=completed&beta=true).** This way you can learn a lot from mistakes of others and see what are the most common ideas and mistakes of kata authors, how reviewers react to them, and what are possible ways to resolve them. +- **Solve more kata.** This way you will get better feeling of what is already there and what topics appear often in search results. Naturally, when you've already solved 10 Fibonacci kata, solving another one will make you very nauseous, making you naturally allergic to duplicates ;-) -## Stick to the intent, focus on one key thing per kata +### Kata quality -If you ask people to do 10 kata about 10 different things, that's okay. +Even the best idea won't save the kata if it's implemented poorly. Lucky for you, there's a set of [quality guidelines](/authoring/guidelines/) which, when followed, will ensure that all pieces of your kata will be created properly. There's quite a lot of them and in the beginning they might seem a bit intimidating, so try to read through them and understand them, before you apply them to your kata. Remember that whenever you have any problems understanding something, you can always [ask for help](https://gitter.im/Codewars/codewars.com/kata-authoring-help). -But if you ask people to do 1 kata which needs to do 10 different things depending on some arbitrary conditions, nobody will ever like the kata. Juggling 10 objects at once is not fun. -This often happens for unbalanced kata - while they're asking for one thing, because of how the kata is written the actual difficulty lies on something **completely unrelated** to the proposed intent of the kata itself, e.g doing a task with a very unnatural and hard to work with input format. +### Learning from experience -If you find that your kata is too long, mostly from these symptoms: -- your kata has a very long description -- a typical solution is very long and yet none of them is hard, the only difficulty is from the tediousness -- your kata requires doing many things together, +There's no better teacher than experience, that's why it's never a bad idea to solve more kata, learn more, and then come back to creating your own. It can help one significantly in the following aspects: +- Getting more experienced will help you *understand* how hard your kata is, so that you can tune your kata to your desire easily. +- As you train more, you tend to know what the most efficient solution for a kata is. This is crucial to performance and golf kata: you don't want to make a performance kata when you can only write sub-par solutions! You'll get pwned hard by veterans ;-) +- Encountering kata issues and looking at comment sections will let you understand the common issues people will raise. Learn from history and don't make the same mistake again! +- Looking at solutions (and more importantly, solution comment sections) will give you an insight into what constitutes good practice. +- It also allows you to see how others write their tests. Writing good tests is **hard**, especially if your kata is also hard. +- By solving and reviewing [beta kata](https://www.codewars.com/kata/search/my-languages?q=&&xids=completed&beta=true) you can learn a lot from mistakes of others and see what are the most common mistakes of kata authors, how reviewers react to them, and what are possible ways to resolve them. -you might want to break up your kata into separate parts if appropriate. +Be aware though that there's many old kata which were created long time ago and do not hold to current standards. Bad quality of an existing kata is not an excuse for creating another bad one! ## Setting up the kata @@ -189,8 +187,6 @@ Remember: just like in real life, if we failed a test, we want to know: So unless revealing the expected result would spoil the kata, you should not hide them. Consult the documentation of the testing framework used by your [language](/languages/) and pick the best method for your tests. - - #### Example Test Cases Example test cases are a small set of tests that the user can see and modify while working on their solution. These are some basic test cases that users will see when they load the kata. Sample tests are written in the same way as submission tests, using the testing framework set up for your language. @@ -200,7 +196,6 @@ Except in circumstances where providing sample tests to the user would spoil the Since sample tests can significantly impact the user experience of a kata, they have a dedicated set of [sample tests authoring guidelines](/authoring/guidelines/sample-tests/). - ## Before publishing When you have finally written all the code, prettified the description, and verified the tests, you consider your kata good to go. But this is a very good moment to take a step back and hold back with publishing the kata, at least for a short while. While working on your kata you were focused on it so much, you probably missed some issues or possible improvements. If you rush publishing it, you risk others will find problems you missed, and your kata will be downvoted, or even insta-retired.