Getting started: solving kata

[hobovsky]

Please take a look if it goes in good direction. I am wondering if it needs screenshots, or links to UI docs will suffice?

[kazk]

Ugh, the output of TextLint is not helpful. I'll look for a way to integrate with GitHub Actions better, but you have a misspelled word on line 23.

[hobovsky]

Yeah it's kinda confusing, but until now I somehow managed to understand it. I will fix the typo tomorrow

[Blind4Basics]

there was still no preview available, so I made a small change/commit.

changed:

After clicking on a link to a kata, you are presented a...

to:

After clicking on a link to a kata, you are presented with the...

[Blind4Basics]

• I'd like a screenshot of the trainer, in the Kata trainer section. Even a small one. Without it, being a new user, I wouldn't get what the documentation is talking about (picture prefereably before the explainations?)

• Overwhole, this is a huge section. By far too much, imo. I feel like the parts about honor and ranks should be in another page. They aren't about "solving" the task, but rather "what happens next". Might be a good idea to rename Viewing Solutions to something like Once you solved a Kata, which would be talking about:

  • rewards
  • feedback

• About "when the tests fail over again" and "unlocking solutions":

  • unlocking might lay into the current page because of the related button. But then I'd put it after the "submit final" section. Note: ## Unlocking solutions, in this case, not # Un...
  • the trouble shooting part doesn't really feel right in this page. It's related to solving, yeah, for sure. I feel like if it's the last section of the page it's ok (then: submit final -> unlock -> trouble shooting -> end)

---

@hobovsky:

• General tip: You tend to write one single § in the small sections while you almost always have an short introductory sentence at the beginning. => split it into 2 different §. ;)

• Question: you tend to not use articles before nouns: ...right. Output panel... while I'd naturally write it as ...right. The output panel.... Is that my french that is making me whish for wrong things or is that your polish at stake? XD

[Blind4Basics]

linefeed+others

Suggested change

	You use solution editor to write code which solves the task. You can type the code straight into the editor, but if you want, you can use your favorite IDE and just copy your solution from it and paste it here.
	You use solution editor to write code which solves the task.
	You can type the code straight into the editor, but if you want, you can use your favorite IDE and just copy your solution from it and paste it here (just don't forget to copy the imports if your language needs some!).

[hobovsky]

About "when the tests fail over again" and "unlocking solutions":

• unlocking might lay into the current page because of the related button. But then I'd put it after the "submit final" section. Note: ## Unlocking solutions, in this case, not # Un...
• the trouble shooting part doesn't really feel right in this page. It's related to solving, yeah, for sure. I feel like if it's the last section of the page it's ok (then: submit final -> unlock -> trouble shooting -> end)

I was trying to follow the "natural" flow of the way how newbie would go through a kata:

1. write solution,
2. Run sample tests
3. Run full tests, which potentially fail many times,
4. Go search for help,
5. Unlock solutions when nothing helps

Order of headers follows this process, which I think is natural and different order seems a bit off to me.

[Blind4Basics]

linefeed+others

Suggested change

	This button will test your solution against the _sample_ tests. 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.
	This button will test your solution against the _sample_ tests.
	Most kata will have provided you with some example tests to get you going, while others will not, in which case some default documentation will be shown instead.

[kazk]

I agree this page is getting too long.

Rewards should definitely go to a separate page.
We should create a page on how to communicate about kata and Feedback can go there.
Unlocking can be briefly mentioned, but maybe linking to a dedicated page explaining the details is better.

[hobovsky]

I split "solving" and "solved" parts into two separate pages. Please let me know what you think.

[Blind4Basics]

• at the root, the gridsome.config.js file needs to be update (for the sidebar) :

...
{
        name: "getting-started",
        sections: [
          {
            title: "Getting Started",
            items: [
              "/getting-started/",
              "/getting-started/registering/",
              "/getting-started/setting-up/",
              "/getting-started/finding-kata/",
              "/getting-started/solving-kata/",
              "/getting-started/kata-solved/",
              "/getting-started/solutions/",
              "/getting-started/community/",
            ],
          },
        ],
      },
...

• It seems there are images at different levels in the folder (07 is outside getting-started/img/) =>?
• would be better to update the images right now with dark/light versions, no? (see Docs Guidelines/How To #74)

[hobovsky]

• at the root, the gridsome.config.js file needs to be update (for the sidebar) :

Done

• It seems there are images at different levels in the folder (07 is outside getting-started/img/) =>?

It got submitted accidentally, sorry. It's to be removed.

• would be better to update the images right now with dark/light versions, no? (see Docs Guidelines/How To #74)

Does it work already?

[Blind4Basics]

Does it work already?

actually yes. I forgot to update the title of the section... XD (corrected)
Note: might be you'll have to move the images outside of the img folder... I didn't explore that correctly yet.

(edit: I'll try it...)

EDIT²: I just checked, that's ok with the info in #74 and the pictures stored in the /img/ subdir (see #85)

[Blind4Basics]

Maybe change the title of the new page to "When kata get solved"? (because other titles are plural, that looks a bit weird in the sidebar)

[hobovsky]

Maybe change the title of the new page to "When kata get solved"? (because other titles are plural, that looks a bit weird in the sidebar)

I tried to fix capitalization, maybe it looks better now.

would be better to update the images right now with dark/light versions, no? (see #74)

Created #86

[Blind4Basics]

I tried to fix capitalization, maybe it looks better now.

👍
that was it, actually :)

[kazk]

It's better document the task and not the buttons.

When you're documenting tasks that involve the user interface (UI), focus on the task, not how the user interacts with the UI element.
https://developers.google.com/style/ui-elements

So instead of Test or Test Button, make the section heading something like Test against the sample tests. Explain that sample tests are for you to edit and test against while writing the solution.

Instead of Attempt of Attempt Button, make the next section heading something like Attempt the full tests. Explain the difference between the full and the sample.

We can improve this later after merging this if you want.

[kazk]

@hobovsky You can merge this if you want. I already left my review yesterday. #72 (review)
We can improve this after merging because all the comments are becoming difficult to keep track.

[hobovsky]

I've already started working on your suggestions, so if you'd want to review my updates, then go ahead, and if you think it;s ok, you can merge it. I will get back to it tomorrow, so if you still think things are good, I will merge my changes. But you can still leave some remarks if you have any, or just merge if you think all is ok.