Kinds of Documentation

[kazk]

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

https://github.com/codewars/docs/blob/409a7cd9482b363e8536266d7f15a1dd3ae66331/data/kinds.yml#L9-L36

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

[kazk]

@hobovsky @Blind4Basics

I decided to name it Kind instead of DocType. See data/kinds.yml. The main 4 kinds were taken from https://documentation.divio.com/.

I think this system is great and would like to follow this. What do you guys think?

[Blind4Basics]

sounds good. I guess we might sometimes have a hard time to choose between recipes and tutorials but... x)

[kazk]

Yeah, it's difficult and the article explains that's why writing a good documentation is difficult. I'd recommend reading https://documentation.divio.com/introduction, but here's my understanding:

Recipes (How-to guides in the linked article) show how to solve a specific goal. The reader isn't new to the topic itself, but looking for a solution for a problem within it. Recipes should present the problem and the solution for it. It can also include some discussions on the problem.

Tutorials are for newcomers. We need to familiarize the reader with the topic. We need to walk them through all the necessary steps and let them learn how things work. Tutorials should only include the necessary information for each step to prevent overwhelming the reader.

• Recipe: "How to write random tests in JavaScript"
• Tutorial: "Creating Your First Kata"