Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Kinds of Documentation #8

Open
kazk opened this issue Jul 7, 2020 · 3 comments
Open

Kinds of Documentation #8

kazk opened this issue Jul 7, 2020 · 3 comments
Labels
enhancement New feature or request

Comments

@kazk
Copy link
Member

kazk commented Jul 7, 2020

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

docs/data/kinds.yml

Lines 9 to 36 in 409a7cd

# keywords: lesson, newcomer, get started
- id: tutorial
name: Tutorials
description: ""
path: /tutorials/
# keywords: how to, problem oriented, one goal
- id: recipe
name: Recipes
description: ""
path: /recipes/
# keywords: describe, list, brief
- id: reference
name: References
description: ""
path: /references/
# keywords: explain, why, concepts, background, discussion, further reading
- id: explanation
name: Explanations
description: ""
# Similar to Recipes, but focused on providing a copy pastable code.
# Recipes can link to these to provide alternative solutions.
- id: snippet
name: Snippets
description: ""

The documentation system

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

@kazk kazk added the enhancement New feature or request label Jul 7, 2020
@kazk
Copy link
Member Author

kazk commented Jul 15, 2020

@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?

@kazk kazk changed the title Organize documents by type Kinds of Documentation Jul 15, 2020
@Blind4Basics
Copy link
Contributor

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

@kazk
Copy link
Member Author

kazk commented Jul 15, 2020

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"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants