Add tutorial

[k-dovgan]

Originally created on Wed, 26 Dec 2018 13:58:39 +0200

Add simple step-by-step guide as an example of usage to documentation.

[k-dovgan]

Tutorials

A tutorial:

• is learning-oriented
• allows the newcomer to get started
• is a lesson

Analogy: teaching a small child how to cook

How-to guides

A how-to guide:

• is goal-oriented
• shows how to solve a specific problem
• is a series of steps

Analogy: a recipe in a cookery book

Explanation

An explanation:

• is understanding-oriented
• explains
• provides background and context

Analogy: an article on culinary social history

Reference

A reference guide:

• is information-oriented
• describes the machinery
• is accurate and complete

Analogy: a reference encyclopaedia article

(https://www.divio.com/blog/documentation/)

[i-keliukh]

Preliminary plan for tutorial or set of tutorials

1. Jenkins setup with node
2. Universum installation
3. Setting up building of the sample project in post-commit
   • The sample project can be hosted in a forked Universum repository
   • Also include local debug
4. Setting up the pre-commit
5. Adding tests
6. Adding static analysis checks with report

[i-keliukh]

2\. Universum installation

This has to be supported by a smoke test after the installation. For the purposes of tutorial it makes sense to allow super-quick creation of test project. Right now, there are bash scripts and configs in the repo that can serve this purpose, but they are not installed as a part of universum installation. Some options:

1. Add tutorial functionality into the universum. For example, with some parameter/function it could generate sample project from template. Benefit: can also be used for creation of project for non-tutorial purposes.
2. Link to the repository. As an option, it could be separate demo project repository. Benefit: project is visible on github even without need to install universum.
3. Let user type everything or copy-paste from documentation. Benefit: easier to implement, all information in one place.
4. Combination of the 1,2 and 3.

@k-dovgan, thoughts?

[k-dovgan]

I'm not sure about templates, especially templates of example source code, but adding interactive universum create-config sounds not that bad. So maybe we can add some simple 'project' (like, one script, maybe?) to the guide and to the 'examples' directory, and suggest user to use this universum create-config on it? And then cite the created config in guide for user to check?

[i-keliukh]

So maybe we can add some simple 'project' (like, one script, maybe?) to the guide and to the 'examples' directory, and suggest user to use this universum create-config on it? And then cite the created config in guide for user to check?

No, this would require user to work with repository. universum create-config should be able to work right after installation and create viable project without any additional sources.

[k-dovgan]

Illia asked to add separate paragraph about updating Universum to newer version for those unfamiliar with Pip

[k-dovgan]

create-config now has it's own issue: #517