Omega Knowledge Base

mega Knowledge Base

Divio Documentation System

Credit to the Divio Documentation System https://documentation.divio.com/

​Allow beginner to get started

Must

Example

• Focus only on 1 way and its steps user need to take

• Minimum necessary explanation, link this

• Concrete steps and user should see result immediately

Writing Guide

TUTORIALS

Steps to install workstation

show how to solve a specific problem

Must

Example

• Focus on achieving practical goal

• Don't explain concepts, link this

• Can allow for slightly different ways of doing the same thing

Writing Guide

HOW-TO GUIDES

How to create a class based view

How to write a test case

describe the machinery

Must

Example

• Structure documentation around code

• Do nothing but describe, link explanations and discussions

• Provide examples to illustrate description when appropriate

Writing Guide

REFERENCE

API documentation

explain

Must

Example

• Give background & context

• Discuss alternatives & opinions

• Explanations

Writing Guide

EXPLANATION

Kafka concepts

Learning

​​Tutorial

Goal

​​How-To Guides

Information

​​Reference

Understanding

​​Explanation

Tutorials does not tell you what you will learn, the learning comes out of doing

How-to guides take the reader through required steps to solve a problem

Reference guides are technical descriptions of the machinery and how to operate it

Explanation or discussions broaden the documentation's coverage of a topic

KEEP TO THE QUADRANT!

You will be tempted to mix the content of each quadrant. Note that overbloating information might not help the reader to get to his/her purpose.

Divio Documentation System

Credit to the Divio Documentation System https://documentation.divio.com/

Multiple Select

What are the 4 types of documentation in the Divio Documentation System?

• How-To Guide

• Tutorial

• User Guide

• Reference

• Explanation

Multiple Choice

Which type of software documentation would be most useful for someone who is new to using a particular software application?

• Tutorial

• How-To Guide

• Reference

• Explanation

Multiple Choice

Which type of software documentation would be most useful to solve a specific problem?

• Tutorial

• How-To Guide

• Reference

• Explanation

Multiple Choice

Which type of software documentation find API documentation?

• Tutorial

• How-To Guide

• Reference

• Explanation

Multiple Choice

Which type of software documentation find list of Pycharm shortcuts?

• Tutorial

• How-To Guide

• Reference

• Explanation

Multiple Choice

Which type of software documentation find Kafka concepts?

• Tutorial

• How-To Guide

• Reference

• Explanation

Multiple Choice

We should only add minimum necessary explanation in Tutorials

• True

• False

Multiple Choice

We should explain concepts in How-To Guides

• True

• False

Multiple Choice

We should add explanations in Reference

• True

• False

Multiple Choice

We should add explanations in Explanation

• True

• False