Situation:

pictures of the different items (categories, glossary, ...) are pretty big, but have no effect. The user has to aim for the text below.

Request:

Extend the link area to the related picture.

A couple of pages related to beta process and beta kata:

• Explanation of beta process, what it is and how it works
• Recipe on how to review a beta kata properly, what to check, when to approve and when not
• Reference of various things related to beta:
  • when kata becomes eligible for approval,
  • mechanism of auto-retirement

Changes are collected in #131 and it's still work in progress, but any ideas, remarks and reviews are welcome.

"Getting started" docs contain links to other areas of docs, which are not available yet. Currently these links are just placeholders marked with TODO, and they need to be filled in when a linked document becomes available.

Occurrences, dumped from VSCode "Find" window:

I:\prv\CodeWars\repos\docs\content\getting-started\community.md
  20,34: See this [detailed documentation (TODO: direct link to Labels reference? same link than the one at the end of the "Communication" part)]() about the different kinds of labels and their use.
  22,46: Discourse posts support [Markdown formatting (TODO: link to Markdown reference)](), so you can use some styling, or present your code neatly with [code formatting blocks (TODO: direct link to chapter on code blocks in Markdown docs)]().
  22,171: Discourse posts support [Markdown formatting (TODO: link to Markdown reference)](), so you can use some styling, or present your code neatly with [code formatting blocks (TODO: direct link to chapter on code blocks in Markdown docs)]().
  30,135: There's a set of rules you should follow to keep interaction with other users a good experience for both sides. You can find them in _(TODO: where? Code of Conduct, some discourse guidelines?)_.
  38,9: - [Chat (TODO: link when ready)]() on Zulip,
  39,19: - Codewars [forum (TODO: link to Discourse forum)]()


I:\prv\CodeWars\repos\docs\content\getting-started\finding-kata.md
  31,64: Details of kata search page are described in [UI documentation (TODO: insert link to documentation of kata search panel)](), but here are some useful hints for beginners:


I:\prv\CodeWars\repos\docs\content\getting-started\kata-solved.md
  21,59: More information on ranks and progress can be found [here (TODO: add link to docs on progress)]().
  25,160: Honor points are rewarded by contributing to Codewars in many ways, and solving a kata is one of them. By earning Honor points you gain additional [privileges (TODO: link to docs)]() and climb [leaderboards (TODO: link to docs)]().
  25,208: Honor points are rewarded by contributing to Codewars in many ways, and solving a kata is one of them. By earning Honor points you gain additional [privileges (TODO: link to docs)]() and climb [leaderboards (TODO: link to docs)]().


I:\prv\CodeWars\repos\docs\content\getting-started\setting-up.md
  17,52: You can find all options described in detail [here (TODO: insert link to actual documentation of UI)](), and below are listed ones useful to get you running as soon as possible:
  22,137: - **Clan** - fill this in if you'd like to team up with your friends, group, or organization. More on Codewars clans can be found [here (TODO: link to clans doc)]()
  28,96: - **Default Catalog List View** - default setting for **"Status"** filter on kata [search page (TODO: link to docs on kata search page)](). Beginners are advised to set it to **"Approved Only"**, but if you want to participate in [beta evaluation process (TODO: link to docs on beta process)](), you can set it to any value you like.
  28,256: - **Default Catalog List View** - default setting for **"Status"** filter on kata [search page (TODO: link to docs on kata search page)](). Beginners are advised to set it to **"Approved Only"**, but if you want to participate in [beta evaluation process (TODO: link to docs on beta process)](), you can set it to any value you like.
  39,63: Again, detailed description can be found in [UI documentation (TODO: insert link to actual documentation of UI)](), but things needed to get you started are briefly explaned below:

I:\prv\CodeWars\repos\docs\content\getting-started\solving-kata.md
  9,69: After opening a kata page, you are presented with the [kata details (TODO: link to kata details panel doc)]() view with general information about it. Read carefully through the description, and if you are ready to face the challenge, you can start your training by clicking on `TRAIN`.
  22,282: t-driven_development) approach. This means that you are encouraged to write not only code for your solution, but also add as many tests in `Sample Tests` panel as you can think of (see [Writing Tests (TODO: add link to explanation how to add more sample tests)]() to see how), for various scenarios, inputs, and edge cases. Most kata will have provided you some sample tests to get you going, while others will not, in which case some test documentation will be shown instead.
  39,287: empt, kata might appear broken, or you receive some errors you do not understand and you have no idea what's going on. Don't worry, there are many ways to get help. See [Troubleshooting your Solution (TODO: add link to FAQ)]() FAQ to get some advice.

Add data/glossary.yml listing Codewars terms and definitions. Generate a page from it and reference to it from other documents.

Use DocSearch when we have contents written. The current search works only for the headers from MarkdownPage.

See #65

We need some documentation for new users. This document should provide information to help them get started without overwhelming them with too many new concepts.

We should discuss what needs to be included first.

Placeholder: https://github.com/codewars/docs/blob/master/content/getting-started.md

Feel free to comment for any thoughts. Also, assign yourself to let the other members know you're going to work on it.

docs/Glossary

Usage of the present thread

To keep this usable: if you wanna suggest ideas, post a reply to this issue. The maintainer/assignee will then update the present message.

Workflow:

• unchecked word: to add
• checked & crossed out: already added
• checked & not crossed out: just added, needs review

In addition, if you may find from time to time some of the following acronyms:

• W: to rewrite
• H: to review / need help or suggestions
• L: needs links to be added

Additional information about how to complete the glossary:

Example

- term: Test Driven Development
  description: A software development process ...
  acronym: TDD
  see: /path/to/a-page/
  links:
    - title: Test-driven Development (Wikipedia)
      url: https://en.wikipedia.org/wiki/Test-driven_development

Structure

type Term {
  id: string;                // (Optional on the user's side) Slugified word. Must be unique. Assigned with `slugify(term)` if unspecified.
  term: string;              // The term in our glossary
  description?: string;      // Description of the term in Markdown. Converted to HTML during build.
  acronym?: string;          // (Optional) acronym form.
  see?: string;              // (Optional) path to a PAGE in our docs. The title will be set automatically
  links?:                    // (Optional) List of external links
     {title: string; url: string}[];
}

The id can be used to link directly to the word

Multiline stuff/descriptions

Use | on the first line

Formatting

Markdowns are supported

Links (see docs guidelines/links)

• Never put a link on the term property (using markdowns)
• links: for external links. Opens the link in a new tab
• see: for internal links, but only to a page, not to an anchor in the page. Opens the link in the current tab.
• To link an entry of the glossary to another one, put the link in the description, using regular markdown. Opens the link in the current tab.

  ...
  - description: See [example tests](/glossary/#example-tests-id)

Traps

Careful with descriptions/strings that contains a colon :...

    description: |
        for katas: blablabla                   // -> WORKS

    description: for katas: blablabla          // -> FAILS

State of the art...

• abandoned kata
• active (author)
• L - allies
• approve (kata/translation)
• attempt
• author
• 'best practices" votes
• L - beta (kata/process)
• L - clan(s) (generic link to use when created)
• "clever" votes
• L - collection(s) (generic link to use when created)
• console
• contributor(s)
• dans
• dashboard
• draft (kata)
• duplicate (Kata)
• edit panel
• example tests
• fixed tests
• L - followers
• forfeit (a kata)
• fork (of a solution)
• honor (need to redact/update the honor/rank files)
• inactive (author)
• initial solution
• L - Issue (comment) (link no writen yet)
• L - kata
• L - kata (search) page
• kumite
• kyus
• language version (with eventual remark on ambiguity of the term, i.e. java version of a kata vs. Mono/C# 7/ C# 8 runtimes
• leaderboard (TODO: detailed article ?)
• markdowns
• L - merge conflict (tutorial about translations to write)
• L - mutation of the input (article to write)
• L - output panel
• performances tests
• preloaded (code snippet)
• progress (need to redact/update the honor/rank files)
• L - Question (comment) (link no writen yet)
• random tests
• randomized tests
• rank
• reference solution (ie. solution of the translator/author, at kata/translation creation / to "nuancate" with the one used for random tests)
• reject (translation)
• L - retire/ed (kata, auto-retirement)
• L - sample tests
• satisfaction rating
• sensei
• solution setup (= initial solution)
• spoiler flag
• submission tests
• "submit final"
• L - suggestion label (comments) (link not writen yet)
• TDD
• test cases
• test suite
• L - trainer (kata)
• trainer suggestions
• translation
• translator
• unpublish

Currently:

when selecting code in code blocks, the background is very dark and the selection is "highlightened" in dark brown, making it close to invisible (it's even worse in light mode, since the outer background is making the selection harder to see).

Expected:

something with "higher contrast"...

Currently, the width of the different pages on docs.codewars may be pretty narrow. In full screen mode, I get this:

Would be nice(r) to either:

• set the default width larger?
• make it autoadaptable to the width of the window itself?

This problem makes the glossary rather massive too: the middle column is as narrow there as it is in the picture above, making some longer definitions looking pretty... "bad" (see the preview of the PR #31 )

Expand https://docs.codewars.com/meta/docs

• https://docsearch.algolia.com/docs/tips#structure-the-hierarchy-of-information

We should write documentation with purpose and target audience in mind.

Reference: https://documentation.divio.com/

Currenlty pages describing a language supported by Codewars are quite comprehensive, but I think they could be both standardized and a bit richer. I thought about including following information:

✔️ - already is there
⚠️ - is there, but could be improved
❌ - is not there, IMO important
❓ - could be useful, but not sure

1. language slug/id used in code blocks and url routes ⚠️ (it;s already there, but not labelled, so I did not even know that what I am looking at is language ID)
2. available runtimes and versions ✔️
3. Timeout ✔️
4. Test frameworks ⚠️ it's already there, but often is missing a version, and it could use a link to the framework reference or something
5. Available packages ✔️
6. Command line used for compilation and running ❌
7. How solution is prepared, built and run: files are concatenated, put in some module, etc. ❌
8. Some interesting details like path to solution file if tests would like to read it ❓
9. Icon used by Codewars ❌
10. Link to CW docs, tutorials and howtos related to the language: authoring translation into this language, creating tests in this language (they will be appropriately tagged, so maybe it's not needed?) ❓
11. Notes on frequently encountered issues or problems (can;t think of anything specific ATM, but I believe there are some) ❓

What do you think? What else would you add?

Currently:

The links are showing up at the same indentation (in red) than the words to define

Suggestions:

• Increase indentation of the links so that the break down of the glossary is more evident/visible (=> in blue)
• increase a bit the size of the xoed to define
• maybe increase a bit the indentation for the description too (keeping link indentation = 2 * description indentation?)

Prepare some kind of HOWTO about creating translations and translations best practices.

I have some idea in my head, but if anyone would like to share theirs, go ahead.

Breakdown of #5 .

Move https://github.com/codewars/codewars.com/wiki/Kata section to new docs.

I plan to move all pages in one go, in initial approach do not focus too much on the content, but move files, update markdowns, add navigation, fix errors etc. Content organization issues will probably appear in the process, and then we can think what move where and how to tag it.

Any ideas, as usually, are very welcome.

I noticed I use "Katas" while hobovsky use "Kata" as plural. Unnamed already talked about that too.

We should always use the same way throughout the whole documentation, so which one will it be?

Move "Honor & Ranks" page from old wiki to new docs (breakdown of #5).

I will think how to organize stuff there to make it clearer and more exhaustive, but if anyone has any ideas or suggestions for this section, Please post them here.

I guess everything is in the title...

See #65

I can't do this right now, and I don't want to forget:

Troubleshooting FAQ could use some additional bullet points in "confusing tests output" section:

• mismatched line numbers (numbers larger than actual number f lines in solution),
• "actual" and "expected" being swapped in assertion messages,
• add some note on the fact that test output panel can be green while tests actually fail (especially on timeout; see codewars/runner#69, check if it still applies).
• Newbies are often confused by JUnit's diff in assertion messages and square brackets present there.

We have some documentation in our wiki. Import the pages that makes sense, restructuring as necessary.

See wiki/ for the files to work on.

all in the title...

todo:

• update the tags once finished
• complete the sidebar in gridsome.config
• write all the "subfiles"

On this page: https://docs.codewars.com/references/ all uppercase links come before lowercase links, what makes for example ZUT appear on the middle page.

Centralization of sets of rules to follow or informations when writting docs.

Table of contents:

Technical matters:

• General organization / update or create new documents
  • Generic procedure to follow
  • Headers hierarchy
  • Sidebar and automatic "table of contents" (ToC)
• Frontmatter for markdown pages
  • How to define it
  • Choosing the right kind of labels for the documentation
• Links to other parts of the documentation
• How to write comments in markdown files

Content matters:

• Way of writing
• Orthograph / choices of words
• Screenshots: both light & dark versions
• Remark containers

Troubleshooting:

• Resolving troubles
  • Problems with correct wording considered incorrect by the linter
  • Usual mistakes to check when the rendering doesn't work

General organization / update or create new documents

Generic procedure to follow

For creating new documents:

1. go to Code
2. create a new branch
3. edit the files, create new ones, add folders, ... all that you need
4. once you're done, go to pull request and create a new one with your new branch
5. wait (maybe a lot... x) ) for the checks to be done, update if necessary, then wait for feedback of reviewers.
6. don't forget to update the topics issue, or tags and kinds files to keep track of the things
7. if you put links to non existing pages yet, create a new issue (labelled ToDo) listing all the links to update later (lines, and related page)

Headers hierarchy

The default hierarachy MUST be precisely followed, because it's used as a base to atuomatically build the ToC.

• # Page Title: must be unique in the document. This is name of the page
• ## Section Title
• ### Subsection Title
• ...

Note: you cannot make "jumps" in the heirarchy, like forgetting ## on purpose and go straight to ###. This will cause rendering errors.

Sidebar and automatic "table of contents" (ToC)

See for example this page: https://docs.codewars.com/getting-started/registering/

• The sidebar on the left is created in the gridsome.config.js document, a the root level.

  1. How to create it:
     • create all the needed files first
     • edit gridsome.conifg.js
     • add the sidebar name to the frontmatter of all the related documents
  2. The steps above can actually be done in any order. If something is wrong at some point, the sidebar just doesn't show up in the rendred pages, that's all (hence, it can sometimes be hard to find what the problem actually his... :/ )
  3. Use the paths of the rendered pages on https://docs.codewars.com/, NOT the actual path of the files in the repo. See the section about links.

• The Table of Content (ToC) is automatically created when the page is rendered according to the headers used in the document. Hence this implies some constraints on those headers/titles:

  1. You have to follow exactly the hierarchy of the headers (see above) otherwise the ToC won't render at all.
  2. You cannot put links markdowns on them (B4B says: if someone finds a way, I'd be happy to update that! XD )
  3. Avoid titles ending with colons or things like that
  4. Choose small titles as much as possible, to avoid things like this... x)

Frontmatter for markdown pages

How to define it

To put at the beginning of the pages, so that the documents are associated with the related "'stuff" (fields are optional):

---
description: ""
kind: reference
topic: markdown
sidebar: docs
prev: /docs/writing-content/
next: /docs/settings/
tags:
  - docc
  - deploy
  - short
---

Warnings:

• Don't forget the whitespaces after the colons... XD (kind:tutorial doesn't work, but kind: tutaorial does)
• For info about how to build the sidebar, see here.
• As any other links perv/next have to be rendered path, not file paths (see links section)

Choosing the right kind of labels for the documentation

See #8 (ext. documentation: https://documentation.divio.com/).

• All available "kinds" defined here.
• All available "tags" defined here.
• All available "topics" defined here (#108 )

Links to other parts of the documentation

• External links: just like usual:
  [text](https://...)

• For links to terms of the glossary, use the following syntax: [text](/glossary/#id), where the id is either the slugified term itself (lowercased string, replacing whitespaces with hyphens) or the id filed if manually defined (code file: glossary ; related issue: #23 ).

• For other internal links to the docs, use the path of the rendered page (not to be confused with the file path!).
  For example, if the Markdown file is at content/foo/bar.md, its (rendered) path is /foo/bar/.
  Exceptions are index.md files: they are treated like index.html so content/foo/index.md is at /foo/.

  file: docs/content/references/markdown/extensions.md
  link; [check the Codewars Mardown extensions](/references/markdown/extensions/)

  file: docs/content/references/markdown/index.md
  link; [check the Mardown reference page](/references/markdown/)

• Alternative syntax using "references", for internal or external links:
  It's possible to define references so that the complete path of the link doesn't decrease the readability of the text:

  link: [check the Codewars Mardown extensions][mark-ref]
  reference: [mark-ref][/references/markdown/extensions/]
  put preferably all the references at the end of the file (see example here)

If you need to put comments in the file, not visible in the rendered page

Use regular html comments:

<!---sqrtgstg--->

Way of writing

#74 (comment): Inspiration can be taken from Google's developer documentation style guide.

Some points to kee in mind:

• Write with translation and a global audience in mind to make it easy to understand by non-English speakers.
• Make clear who's performing the action
• Use second person. "It's generally best to avoid our."
• Use descriptive link text that is helpful to the reader
• Put conditional clauses before instructions, not after

Orthograph / choices of words

• website name: Codewars, not "CodeWars"
• plurals: use Kata, Kyū, Dan, Kumite (#63)
• terms to avoid: codewarrior(s), prefere user(s)

Screenshots: both light & dark versions

See #71, #85

Pictures can be stored in a subdirectory if needed. Preferably called img if used.
Related code:

<ThemedImage
  alt="Follow Button"
  sources={{
    light: require("./img/follow_light.png").default,
    dark: require("./img/follow_dark.png").default,
  }}
/>

Remark-container to support callouts

See #164

Documentation: See https://gridsome.org/plugins/gridsome-plugin-remark-container

Syntax

:::keyword optional_title
some content
:::

Examples of info boxes (that's how they look at the moment of writing, but they can be modified, extended, or styling can be changed), with in order: tip, note, details, important, warning, danger

Troubles with the linter/rendering engine

Problems with correct wording considered incorrect by the linter

(related: #7)

If you need to temporarily deactivate the linter (ex: "the data is built in suach a way..." raises an error asking to change for built-in), use this:

<!--- textlint-disable -->

...(your problematic paragraph here)

<!-- textlint-enable -->

or

<!--- For false positive "built in" -->
<!--- textlint-disable terminology -->

...

<!--- textlint-enable terminology -->

Usual mistakes to check when the rendering doesn't work

• If you get everything in red in the pull request, here are some things to check:

  • Click Details on the result of the linter check to see if some words or expressions are considered invalid (see above)

• If the linter is ok but not the other checks, verify that

  • the different headers are consistent through the page:
    • you need to have # as title
    • you cannot "jump" in the hierarchy, if you have ###, you must have # and ## somewhere before

• If all checks are green and the ToC or the sidebar aren't showing up:

  • check your headers hierarchy
  • check how to build the sidebar

From #124:

For "how to write comments effectively", we can do a Codewars version of Getting Answers (or How To Ask Questions The Smart Way). We should have something to point to with good examples when we have a user who doesn't know how to ask a question or opens issues too quickly. We can also show this before their first comment in the future.

currently:

15 pages with only 4 references shown at the same time.

expected:

to see more of them at the same time (but how much??)

Breakdown of #139.

Any ideas and/or links to existing stuff are welcome.

For kata description, we should have some recommended style (what to include, how to structure, etc).

#67 (comment)

I will also include a note that not all guidelines fit all types kata and some of them can be ignored if not applicable.

Proposed guidelines:

• Some of these guidelines do not apply to every type of kata. Use where applicable, so not use where not.
• Keep as language neutral as possible
• Descriptions should be written in English. Proofread, ask for help if necessary.
• Ask others if it's clear enough, consider their suggestions
• Formatting
  • use formatting, markdown, katex for readability. Avoid visual noise and excessive formatting. Consider proper header levels.
  • avoid HTML
  • use language code blocks
  • avoid descriptions mentioning many languages. use conditional blocks (link) for language specific parts.
• Requirements
  • Describe all requirements and edge cases, leave no surprises
  • Provide examples, use images when helpful. Avoid "see sample tests for more examples".
  • Describe or hint the difficulty: input ranges, volume of tests, minimum expected complexity, etc.
• Structure
  • split the description into meaningfull sections. Example:
    • overwiew/context (if needed)
    • task
    • input/output
    • rules/details
    • notes / technical details
  • try to regroup informations of the same kind: explaining inputs specificities at 3-4 different places isn't a good idea
  • the task section must stay short. Its goal is only to give an idea about what's going on. Going right there into details will just lose the user. So stay consise but precise.
  • it's generally better to explain going from general things to details/exceptions/edge cases. Not the opposite.
• Other
  • links to knowledge (hints, algorithms, papers)
  • link related problems (variants, difficulty tiers)
  • give credit when necessary
  • include Preloaded

Currently

At the moment, these kind of links can be assigned to Terms objects:

• external links, through the links property
• links internal to codewars.docs, thourgh the see property

It's not possible to link terms of the glossary between them

Expected

Be able to link terms of the glossary to one another, like:

• Example tests: blablabla
  ...
• Sample tests: see example tests

Suggestion

Add... something... and what's needed with it so that one (or even both) of the following is possible:

• Either: adding the link to the other term inside the description of the Term.term property of the target

- term: Sample tests
  description: "See [example tests](#Example-tests)."

• Or having a link added automatically through a new property like this:

- term: Sample tests
  description: ""
  anchoredTo: "Example tests"

or possibly, to avoid to have to update that new property if a term is changed:

- term: Example tests
  description: ...
  anchor: ThisWouldBeAnAnchor

...

- term: Sample tests
  description: ""
  anchoredTo: ThisWouldBeAnAnchor

And that would automatically add the link below the term in the glossary, linke the links or see properties.

the anchor property could be by default a "slugification" of the term propoerty as long as it's not defined.
Both would be optionnal.

Link to Zulip when we're ready to allow normal users to join. Write some guide to educate users how to communicate effectively.

I'm going through @Kask's message on zulip, and I'm wondering if we shouldn't try to only use the [text][refLink] syntax: this way, the actual links are stored once and for all at the bottom of the file, so if ever an update is needed, it's way easier to maintain.

Opinions?

Example (the index page for the markdowns):

Codewars supports [Markdown][wiki-markdown].

More specifically, [GitHub Flavored Markdown][gfm] (strict superset of [CommonMark][common-mark]) and few [Codewars extensions][extensions].

<!-- the following lines are defining the links and aren't visible in the rendered page -->
[wiki-markdown]: https://en.wikipedia.org/wiki/Markdown
[common-mark]: https://commonmark.org/
[gfm]: https://github.github.com/gfm/
[extensions]: /references/markdown/extensions/

I'll update #74 accordingly.

Here we can discuss more in detail what should be added there. I'll store some ideas at the same time.

First, a lot of things when it'll come to explain how to write "good tests" will be pretty generic. So I believe we might actually writte that generic version first, listing there some of the usual traps to avoid.

Then a more precise guide, python specific.

Generic guide:

Here are some ideas to use as a stump:

structure of the kata/tests suites

• always fixed and random tests (explaining why: not usual TDD practice, needed to enforce the implementation/avoid cheats).
• split the test suite using meaningful names for the different blocks
• write the assertions inside the dedicated structures (groups/blocks/methods) rather than at the base level (when it exists in the language)
• one day you'll maybe stop coming on CW, so other people will have to maintain your kata. So think about them and try to write your best code for your tests. DRY, no functions with tens of line, ...
• explain how the test framework is working (generally speaking), printing the results/data needed for the feeback right to the stdout, meaning that the user can/will print in the middle of all of this. Hence the need to:
  • never do several calls to the user's function then do all the tests later. That makes the debugging a pain because the user cannot track hat assertion is related to waht call to his function
  • when possible and adapted to the test framework you use to have one single call to the user's function per test method.

tests feedback

• be very carful about the assertion messages: they have to be precise and useful. "False should be True" almost always trips up newbies. General guidline: it's good to show the input, either in the assertion message, or in the name of he test (if the test framework allows to name the tests). Like: "28 is not prime. Answer should be False, but solution returned True." would be much better (hobo ; error256).

fixed/sample tests specificities:

• having only 2 fixed tests before the random tests is generally a very bad idea
• do not hide edge cases in the test cases part, provide them int the sample tests too (hobo).
• You can use all the fixed tests of the test cases part as sample tests. But if it's very long, it's not always necessary. But when you remove some of the fixed tests, try to keep at least one meaningful test for every kind of situation (hobo)

random tests specificities:

• for the random tests: prefer, when possible, to avoid to have a reference solution => design the tests so that either you know the answer right at the beginning when the input is generated if possible (hobo)
• performances oriented katas: when the random tests use inputs/outputs that are very hard to debug (strings of hundreds of characters or more, huge arrays, multidimensionnal arrays, ... anything that akes the assertion message unreadable!), split the random tests in 2 sections or more, with a first batch of small random inputs. (error256)
• the "mutation of the input" problem takes all its meaning in the random tests (give examples):
  • why it's bad in general
  • why it's bad on the user side (crazy feedback)
  • why it's bad for the tests (cheatable)

miscellaneous

• don't rely on the random tests to enforce the requirements: all possible edge cases should be exhaustively tested in the fixed tests. As far as possible. When not possible, they should be added later if a user encounter one of them et raise an issue about it. (error256)
• This do not apply to all framework, but keeping it as a habit/default behavior might avoid a lot of troubles to anyone:
  • do never compute directly the expected result with a formula in the same statement than the one calling the user's function (raising an exception reveals the solution) -> is that python specific? (I guess not...)
• all rquirements that are announced have to be tested (hobo). Like, if the user isn't supposed to use BigInt, the author has to enforce it, etc. Adding a note: "Keep in mind that when you end up with this kind of idea, you're generally about to open the pandora's box. Especially in languages that are too much flexible, like JS, pyhton or ruby. So you actually should try to avoid restrictions that may be very hard to ensure. Number of lines or length of the code, on the other hand, is not problematic (code golfing)".

general infos about the guide itself:

• "this guide is still generic, so it might not cover all cases or even not be appropriate for some languages whose framework works in a different way (QuickCheck for Haskell, for example). Please refer to the documentation of your language and/or ask for help to other experienced users." (error256)

Additional sources

• interesting ideas to gather from here (hobovsky's "kata authoring guidelines" draft)

python specific guide:

• always put the assertion methods inside a it block rather than at the top level or in a describe block, especially for the random tests. This way, when the tests are passed, the user doesn't end up with a wall of Test Passed! in the output panel (in addition, this allowes to see the timings for the block(s) without the need to scroll all the way down.
• insist one the mutation of the input trouble, because of the order of actual and expected in the assertion methods => always compute the expected value first is the best idea to get

per language:

(or not!? B4B)
add snippet explaining how to access the solution of the user (length/chars constraint)

Feel free to dump some ideas.

This is a reminder coming from this message in Finish the Markdown reference/tutorial:

(B4B)

• Do you (plural) think we need a tutorial or recipe about markdowns yet?
• If so, do we make it a stand alone thing, or do we rather incorporate it to something else (like, writing descriptions)?

(kazk)

Not really for Markdown itself, but I think we should have something for "how to write comments effectively" and also "how to write kata descriptions". For kata description, we should have some recommended style (what to include, how to structure, etc).

Docs could use a set of recipes with guidelines on authoring: creating kata, translations, writing tests, etc.

My current idea is to create structure of docs with following sections:

• set of articles for specific snippets, so they could be referenced by other parts. Keep them language-agnostic and present ideas and best practices behind them.
  • general coding guidelines (#145)
  • full tests (#19)
  • description (#143)
  • sample tests (#146)
  • proposed solution (#147)
  • preloaded (#148)
• find good place for language specific follow ups on above snippets (like #17). Probably location would be similar to how #115 was realized?
• creating kata (#149)
• creating translation (#134)
• creating kumite? (#150)
• create separate issue for every page to collect ideas, feedback and for better tracking. Link them here, maybe as a checklist? A couple of issues is already there.
• prepare structure in repo, create stubs, think on frontmatter stuff (tags, navigation, etc)
• when working on some article, update links and references to TODOs docs which will become outdated or moved (remember about sidebar!)

What do you think?

See #74 how to do this.
Prepare light mode equivalents of screenshots, put img references in md files.

Remove the placeholder docs from the starter and fix any affected parts (e.g., sidebar, missing fields).

Suggestion from kazk:

Any idea where CoC and organizational stuff would fit in current docs and in repo?

Maybe under /community.

• /community overview
• /community/teams/ organizational stuff. List of admins, mods, explain crown/shield, etc.
• /community/rules/ list of things that's not allowed within the Codewars community. The current CoC might need rewrite, I read somewhere that it's better to list things you're not allowed to do explicitly rather than listing how you should behave because the latter can be subjective.

I do not have a good idea how to reorganize CoC, so maybe, for the start, I will just import existing one. I will think about it.

Another question would be navigation: how to get there from the landing page? Use some other kind of doc? Or make it a concept of community?

Ideas are welcome!

WARNING

those links are from the first version of the troubleshooting page (before splitting)

244: to create: [code formatting TODO](https://github.com/Codewars/Codewars.com/wiki/Markdown-Formatting) 
250: to create: [this Codewars wiki page TODO](https://github.com/Codewars/Codewars.com/wiki/Kata-Discourse)
260: Zulip? [general TODO](https://gitter.im/Codewars/Codewars.com) 
       Zulip? [kata solving help TODO](https://gitter.im/Codewars/Codewars.com/kata-solving-help)

file (once merged): https://github.com/codewars/docs/blob/master/content/recipes/troubleshooting-solutions/troubleshooting-your-solution.md

We agreed that some forms should not be used. We were also advised to avoid some constructs. Maybe we could enforce them with additional linter rules? There's already rule for CodeWars, so maybe we could also have:

• plurals mentioned by B4B: katas, dans, kyus, with abominations like dan's or kyu's
• kyu, as opposed to ky-u-with-dash-above
• codewarrior as a term to avoid,
• dojo and others with remark to reduce usage of the theme?

Maybe you can think of some more. They don't have to be errors, they can be warnings if appropriate (yeah, I read through warnings, usually)

What do you think?

For some screenshots, it might be better to use the version matching the current theme (dark mode on/off).

This should be possible using dark:hidden and dark:block variants:

<div class="block dark:hidden">

![alt](./light.png)

</div>
<div class="hidden dark:block">

![alt](./dark.png)

</div>

Wrapping in <div> because we can't use <img> tag with relative paths in Markdown at the moment.

• markdown home page
• extensions page (reference)
• some sort of tutorial, but where/in what section? (see message below) -> will be added somewhere else, see below

#62 added a stub page for basic Markdown syntax and we need to complete it. The page should be minimal and easy to scan. Any nonstandard Markdown features were extracted into a separate page.

Basic Markdown that most users use is extremely simple and should focus on that. For example, GitHub's Markdown Cheat Sheet looks like this:

Include the syntax for:

• Emphasis
• Code Block
• Lists
• Links
• Blockquotes

I'm not sure if it's worth including the result. For most of them, it'll look very similar to the original syntax and it's pretty obvious. It can look slightly different on Codewars because different libraries are used and CSS is different. For Headers, it'll also mess with the table of contents as well.

/concepts/kata/translations.md has some placeholders to be filled in with links to documentation which is yet to be written:

• translation authoring guidelines (dedicated issue: #134 )

NUnit: https://github.com/nunit/docs/wiki/Multiple-Asserts
junit: https://junit.org/junit5/docs/current/api/org/junit/jupiter/api/Assertions.html#assertAll(java.lang.String,java.util.Collection) (or https://junit.org/junit5/docs/current/user-guide/#writing-tests-assertions)

To get a better idea about how the thing will eventually work:

Currently:

Suggestions/questions:

So, I guess every "entry point" for documentation will land as an icon in the bottom part of the screen. This leads to some questions:

1) how are they organized?

reading through https://github.com/codewars/docs/blob/master/src/pages/Index.vue, it seems they are automatically displayed in the order the components are inserted into this file (g-link parts). Right?

2) is it possible to visually separate them?

Like, to have line separations or something in the home page to split some icons from others?

3) when more things will be there, what general organization should we use?

On this, and if the previous point is possible, I'd see the following:

• first icons: glossary/category/tags/supported languages (on the same line if possible)
• an horizontal line
• all other topics by alphabetial order

4) what other topics?

Here is the critical point, imo. 'Time to define some ways of splitting the docs so that we can have a better idea about where we are going.

I'd go for the followings (in random order and non exhaustive, ofc), the idea being that those categories could contain sub parts possibly used at several different places:

• getting started (not sure if it's good to have it doubled with the link in the center of the page but...). See #40

• codewars general informations, that would roughly be filled with :

  • https://github.com/codewars/codewars.com/wiki/About-Codewars
  • https://github.com/codewars/codewars.com/wiki/Kata
  • https://github.com/Codewars/codewars.com/wiki/Honor-&-Ranks (more detailed version of what would be in the "getting started/finding-kata.md" part
  • https://github.com/codewars/codewars.com/wiki/Community-Code-of-Conduct
  • ...

• codewars UI (detailed/exhaustive version of what I suggested to add to the "getting started" part. Not entirely sure it deserves a specific topic, tho)

  • ...

• beta process

  • ...

• kata authoring and translating
  (I put the info there otherwise it could be lost in zulip at some point: authoring tutorial: give credit to the original source when needed)

• Codewars' users

  • regular/red users
  • moderaotrs/team/admins (assuming "moderators" become something different from PUs)
  • power users
  • link again to the code of conduct
  • privileges
  • Social aspects (clans, followers, ...)
  • ...

• tutorials (possibly linking other parts in the previous sections).

  • markdowns
  • troubleshooting
  • create tests/snippets(?)
  • the "getting started" tutorial should be present there again (might be a better idea than to put is as an icon in the home page)
  • how to debug your solution using the console
  • ...

• Maybe a FAQ section would be a good addition. That would only be another way for the users to go/access to informations spreaded in other places (idea comming from @Steffan153 's post on zulip )

Here are my 2 cents...

@kazk: is that in your line of thougths for the docs?

Some other ideas randomly stored there

• reference
• guide/tutorial

We currently have two Python test framework docs.

• https://github.com/codewars/docs/blob/master/wiki/codewars-python-test-framework.md
• https://github.com/codewars/docs/blob/master/wiki/codewars-python-test-framework-v2.md

Based on these, we should create:

• A guide for writing good tests with it (read few times when starting)
• A reference manual you can refer to (read multiple times)

The guide should describe how to write tests. The reference should list all the assertion functions and example usages.

Later, we can also add another page for specific topics, e.g., writing random tests.

Feel free to comment for any thoughts. Also, assign yourself to let the other members know you're going to work on it.

Move "Privileges" page from old wiki to new docs (breakdown of #5).

I will think how to organize stuff there to make it clearer and more exhaustive, but if anyone has any ideas or suggestions for this section, please post them here.

Any hint on where it should be located in current docs could be helpful.

Here are listed the topic fields used throught the whole documentation, in alphabetic order.
Topics are used to identiify the subject of the page/group of pages. It is (will) be used to build the table of contents.

Goal: avoid spreading the same topic on different keywords (like test, tests, testing, ...)

Topics

• markdown
• tests

I have more than 1500 reputation and already created a couple of Javascript kata

I´d like to create a sql kata, but I have no clue about how to start with

Is there a tutorial or a complete example that I could have a look at?

I can only see the test cases but I don't know how to setup the initial data (create table, inserts, etc) or the expected result.

thanks a lot

C++ kata often produce unhelpful assertion messages, because authors do not know how to work with stringizers and other mechanisms of Snowhouse framework.

See Getting better output for your types for reference and provide some example how to create a stringizer for custom or library types (std::pair<int, int> being quite common), and where to put it in the kata (preloaded, tests?)