Add Getting Started doc

[kazk]

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.

[hobovsky]

I was thinking how to tackle such idea and I came up to a couple of conclusions. I ended up with idea which can be described with following conspect:

• Creating account (is it relevant? Will docs be available for a user who's not signed in?)
• Your account, containing information on:
  • dashboard
  • profile panel
  • account setup
  • training setup
• Getting a kata to solve
  • training suggestions,
  • kata search page
  • newsletter
  • kata "numbers": rank, satisfaction, possibly others (which? maybe tags) as criteria for selecting a kata to solve
• Solving a kata
  • Trainer, submitting a solution
  • Solution troubleshooting
  • unlocking solutions / forfeiting a kata
  • reward: honor, progress, privileges
  • satisfaction voting
• Solutions: viewing, voting,
• Participating in discussion
  • Discourse, posts, spoilers, post labels
  • out-of-site places: gitter, zulip, forum

I think "Getting started" does not need to cover things like translating or authoring a kata, or kumite, because these are not "first contact" activities. I focused on things needed for users being on-boarded.

What do you think?,

[kazk]

Looks great.

Creating account (is it relevant? Will docs be available for a user who's not signed in?)

Anyone can view the docs so it might be worth having a page that can be linked from the getting started page (e.g., "If you don't have an account yet, see ...").

I think having separate pages for each of the areas and using the prev/next links will be good. We can also have a "getting started" sidebar listing all of those pages that shows while on the relevant pages.

[kazk]

I think "Getting started" does not need to cover things like translating or authoring a kata, or kumite, because these are not "first contact" activities. I focused on things needed for users being on-boarded.

Completely agree. I want new users to focus on solving and getting used to the platform.

[hobovsky]

Glad you like it, if you have any suggestion, just post here.

I will think how to get moving with this, but honestly, I do not even have an idea how to start with this doc system :( I would need some help with questions like:

• where to put the files (main/toc and subpages),
• some template to have sidebar, navigation and other stuff available

Knowing this, it will be much easier for me to start and will save us a couple of bogus commits just to "check if it works and what's still missing".

[kazk]

Sorry, I wrote some info in README, but I should have documented better. I'm building on top of a template and some of its documentation is still relevant. I kept them for placeholder so it's still available at https://docs.codewars.com/docs/

where to put the files (main/toc and subpages)

Any Markdown files under content/ creates a matching page.
For example, content/getting-started.md is at https://docs.codewars.com/getting-started/

If we're writing groups of pages for "Getting Started", it might be better to create a folder content/getting-started/ instead and move content/getting-started.md to content/getting-started/index.md (index.md works like index.hml so the path won't change). Then add subpages and any other assets like images in that folder.

ToC is generated automatically based on headings so no need to do it yourself.

some template to have sidebar, navigation and other stuff available

To add a sidebar, add new sidebar entry in:

docs/gridsome.config.js

Lines 23 to 35 in f18bdf2

	sidebar: [
	{
	name: "docs",
	sections: [
	{
	title: "Getting Started",
	items: [
	"/docs/",
	"/docs/installation/",
	"/docs/writing-content/",
	"/docs/deploying/",
	],
	},

and set the sidebar of the page with Markdown frontmatter (YAML at the top of the file). For example, this document has sidebar named "docs":

docs/content/docs/deploying.md

Lines 1 to 11 in f18bdf2

	---
	description: ""
	category: docs
	sidebar: "docs"
	prev: "/docs/writing-content/"
	next: "/docs/settings/"
	tags:
	- docc
	- deploy
	- short
	---

See also https://docs.codewars.com/docs/sidebar/

To have prev and next navigation links, set them in the Markdown frontmatter as above. See https://docs.codewars.com/docs/settings/#next-and-previous-navigation

The placeholder documents that came with a template should be useful examples (https://github.com/codewars/docs/tree/master/content/docs).

Feel free to ask if you have any other questions.

[kazk]

I decided to create the pages, sidebar, and navigation so you can focus on the content.
See https://github.com/codewars/docs/tree/master/content/getting-started and #42 for the changes I made.

This should be good enough for a start.

[Blind4Basics]

Maybe we should move all the "placeholder" files in a dedicated folder, so that we can have a clear view of the current state of the docs and their architecture?

EDIT: I mean, this page, for example, is currently quite confusing because it displays at the same time valid codewars related infos but the table of contents is only made of placeholders.

[Blind4Basics]

I think a category is missing: something about "Codewars UI", explaining how to navigate through the interface, what data can be found here or there, ...

In between Setting up your account and Getting a kata to solve, I'd see a Navigating through codewars or something like that.

eidt: any idea why markdowns formatting aren't working in my message? :o

[hobovsky]

What placeholder files you mean, exactly? If you mean stubs created by kazk for "getting started" then I think they do not need to be moved anywhere, I will start working on them soon so they are in a good place now, I think.

@kazk thanks for preparing stubs, I should be able to pick up from here. I have one question though: I would like to create some screenshots with UI elements so people would know what I am talking about. It does not bother me if I can use only my personal account and screenshot it, but I wonder if it would be a problem if I created some new, temporary, dummy account so I could recreate newbie's path through the system, screenshot popups etc. I could also fake some views with dev tools, if I only find out how to show information about events which I've already progressed through. Or maybe such thing is already available? I mean something in spirit of B4B's codewars/codewars.com#2199

[Blind4Basics]

What placeholder files you mean, exactly? If you mean stubs created by kazk for "getting started" then I think they do not need to be moved anywhere, I will start working on them soon so they are in a good place now, I think.

Na, I was talking about the stuff that currently is in this

About screenshots, you can use the way @kazk showed me for the python test documentation (wait a sec, I'll update with the relevant link)

edit: here it is: #17 (comment)

[kazk]

@hobovsky Sorry, I missed your comment. We've already talked about the temporary account on Zulip, but I noticed you mentioned the popup. It might make sense to maintain them here. I'm thinking of showing the docs on Codewars through iframe and popups can be done similarly. Also, a good idea to add some way to see the popup again after closing it.
I haven't decided what to do yet, but I'll copy some popups into this repo for reference.

@Blind4Basics

Maybe we should move all the "placeholder" files in a dedicated folder, so that we can have a clear view of the current state of the docs and their architecture?

Na, I was talking about the stuff that currently is in this

It's already in content/docs which will be removed sometime soon.

I'll start creating stubs for other pages so it's easier for you guys to work with.

[kazk]

Added https://github.com/codewars/docs/tree/master/popups for reference.

[hobovsky]

I created #57 and have some questions:

I am wondering if images are not too large. My initial version of them was quite overwhelming, I reduced them a bit and now they look a bit better. Tell me what you think.

I also wonder how the page will look in both dark and light mode, I believe we can check this only after docs are rendered and deployed?

I was not sure about the style, is it ok, or should it be somehow different? More of dojo theme? Any suggestions?

Any English native speakers volunteering for future review requests? With me and B4B reviewing each other's edits, we can only imagine what kind of wild Slav-French pidgin will end up with :D

[Blind4Basics]

With me and B4B reviewing each other's edits, we can only imagine what kind of wild Slav-French pidgin will end up with :D

XD I'm reviewing tho... ;p But yeah, for sure... x)

edit: reviewed. But I don't know how to properly do it, like kazk did on mines... So I just copy/pasted full § and made modifications in there... :/

[kazk]

@hobovsky

I am wondering if images are not too large. My initial version of them was quite overwhelming, I reduced them a bit and now they look a bit better. Tell me what you think.

The images look fine to me. The build process will optimize the image and use different sizes based on the screen size.

I also wonder how the page will look in both dark and light mode, I believe we can check this only after docs are rendered and deployed?

You can check the preview deployment.

I was not sure about the style, is it ok, or should it be somehow different? More of dojo theme? Any suggestions?

Do you mean the writing style? I think it's fine. To be honest, I personally don't really like having too much dojo theme because it can be confusing and the newcomer is forced to learn extra terms. Most (some can be "fun") of the documentation should be optimized for clarity.

Any English native speakers volunteering for future review requests? With me and B4B reviewing each other's edits, we can only imagine what kind of wild Slav-French pidgin will end up with :D

I'll review it. I'll also look into more tooling for automated reviews.

@Blind4Basics

https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request

[Blind4Basics]

👍 got it, thx

[kazk]

With me and B4B reviewing each other's edits, we can only imagine what kind of wild Slav-French pidgin will end up with :D

I don't think we need to be too strict at this point. I had let go many descriptions in the glossary to keep us moving. Writing documentation is hard, especially in a foreign language, so don't worry too much or get discouraged. We can always fix confusing parts as we go and I'm hoping we'll get more contributions once we make this more visible.

[hobovsky]

Account setting "Development experience" is duplicated in account settings and training setup views. Any specific reason for that? Any good idea how to describe it, especially in context of "Getting started" tutorial?

[kazk]

I can't think of a reason.

I think it used to get used for the training routines (each language used to have experience option too), but I'm not sure if it's currently being used other than understanding our user base.

It's probably in the "Training Setup" because that's shown after signing up. It's pretty common to ask when your product targets devs. For example, GitHub shows this after signing up:

[hobovsky]

About ./my-profile @kazk asked in one of reviews: it should be a link to regular user dashboard, but this anchor is a leftover from my attempt at tackling this B4B's idea:

I think a category is missing: something about "Codewars UI", explaining how to navigate through the interface, what data can be found here or there, ...

In between Setting up your account and Getting a kata to solve, I'd see a Navigating through codewars or something like that.

I was considering such page with some brief description of UI elements a newly registered user can be interested with, on dashboard and on "User Profile" page. However I am not sure if it's really necessary in "Getting started" guide and maybe just some reference to UI part of docs would suffice?

I can't think of a reason.

I think it used to get used for the training routines (each language used to have experience option too), but I'm not sure if it's currently being used other than understanding our user base.

It's probably in the "Training Setup" because that's shown after signing up. It's pretty common to ask when your product targets devs. For example, GitHub shows this after signing up:

Any idea how to describe it in "Setting up" part of "Getting started"? Skip on one, duplicate, or describe in one part and link to it in the other?

[kazk]

I don't think we need to describe every single element, so we can skip it for now.

[hobovsky]

In my tutorial there are some references to documentation which is not ready yet. They are marked with TODO: insert link to... . How should we handle these? Is it OK to keep them for now as they are, remove them until referenced document is ready, or remove "TODO" annotation and just leave a properly labeled, but dead link? Do you have some other suggestion?

[Blind4Basics]

I'd go with proper labelling and TODO showing up, so that it's easy to find them later

text text text text see [this reference (TODO)](...?)

[hobovsky]

Anything still to be done in scope of this issue? "Getting started" is added, and follow up todos are created as dedicated issues, anything left to do here? Or can it be closed?

[kazk]

We can close it. Thanks