Create Interactive Tutorial

[markus2330]

An interactive tutorial similar to

https://try.github.io/ done with https://www.codeschool.com/

might be an interesting option to learn kdb.

[markus2330]

Or also non-interactive, see: https://github.com/adambard/learnxinyminutes-docs

[kodebach]

https://github.com/googlecodelabs/tools is a tool by google for creating step by step guides.

All the guides created by google can be found here: https://codelabs.developers.google.com/

[stale]

I mark this issue stale as it did not have any activity for one year. I'll close it in two weeks if no further activity occurs. If you want it to be alive again, ping the issue by writing a message here or create a new issue with the remainder of this issue.
Thank you for your contributions 💖

[stale]

I closed this issue now because it has been inactive for more than one year. If I closed it by mistake, please do not hesitate to reopen it or create a new issue with the remainder of this issue.
Thank you for your contributions 💖

[aaronabebe]

How in depth would the tutorial need to be? What different features would you have in mind?

[kodebach]

@markus2330 can probably give more information here, but I think the idea was that you get a different number of points depending on the scope of the tutorial.

Some examples for possible to tutorials would be:

• "Elektra basics": A very basic tutorial explaining the basic concepts of Elektra (key-value, KDB, mounting, etc.) and showing them off with some kdb commands or other examples. Not sure, how well this would work interactively. I think you would end up with a lot of text and a few interactive bits in between.
• "How to create a new application that uses Elektra?": The end result would be similar to the applications in examples/external. Probably something more fully featured like the ones in examples/external/codegen would be better than the very basic ones that just print a single key.
• "How to use XYZ binding?": Setting up an application with a binding.
• "Writing a specification": Instead of focusing on the code of the application, the tutorial would focus more on how the specifications work.
• "How to write a plugin for Elektra?": Step by step guide to writing a plugin. Probably only for a simple validation plugin that doesn't create any keys and only validates one key at a time. More complex validation plugins and especially storage plugins can be quite tricky and the tutorial should probably be written by someone with a lot of experience.

IMO the most useful version would be a basic getting started tutorial, since there are not many (concise) resources in that area currently available. Although, like I said, the result might not end up being very interactive. That wouldn't actually matter that much. A good non-interactive getting started guide would also be very nice. I just assume you are interested in the interactive part (since you asked in this issue).

[markus2330]

How in depth would the tutorial need to be?

The better it is understandable and the more in-depth it is, the more points you get. For a tutorial covering some basics it is about 3 points. For a more advanced tutorial (which does not exist yet) it can be 7 or 13 points.

What different features would you have in mind?

In your case probably something about Elektra's specifications or Java makes sense. It can be anything but make sure to propose first what you want to do.

[philippoppel]

i would like to make an interactive tutorial for

• java binding
• maybe a gettingstarted tutorial with visuals in qt-gui

[markus2330]

@philippoppel @aaronabebe do you plan to do this together? If not, @aaronabebe what will your topic be?

[philippoppel]

No we did not plan anything together

[markus2330]

@philippoppel You can write about the Java binding, please contact @tucek for any questions and coordination about Java binding tutorial.

@aaronabebe Please write more about the topic.

[aaronabebe]

@markus2330 I was thinking of doing an interactive tutorial for writing a specification. A specification lends itself to be written step by step and I think that could work really well as a sort of interactive environment.

EDIT:
I will be using https://github.com/googlecodelabs/tools if that is ok.
What would be the ideal way to publish the tutorials when finished (just the index.html of the tutorial, or more stuff, like landing-page, etc.)? Or where do we plan to host them?

[markus2330]

@markus2330 I was thinking of doing an interactive tutorial for writing a specification. A specification lends itself to be written step by step and I think that could work really well as a sort of interactive environment.

Perfect, so there will be no overlap to @philippoppel's work.

I will be using https://github.com/googlecodelabs/tools if that is ok.

We don't have any experience with interactive tutorials yet. You can give it a try.

Which interactions do you plan to do? Plain Markdown is also an option.

What would be the ideal way to publish the tutorials when finished (just the index.html of the tutorial, or more stuff, like landing-page, etc.)? Or where do we plan to host them?

We will definitely host all good tutorials.

Maybe we can even integrate it in https://www.libelektra.org in the tutorial section?

@Namoshek do you have a suggestion how we could integrate them? (According to https://github.com/googlecodelabs/tools "How do I publish my codelabs?" there seems to be a html and markdown option.)

[aaronabebe]

Which interactions do you plan to do? Plain Markdown is also an option.

I made a step by step example to mount and create a specification for an example project. You can find the detailed info in the PR I did for this issue, or look at my hosted version at https://aaronabebe.gitlab.io/#0.

Regarding the integration, I think the easiest way would be to just integrate the generated index.html file. Using the claat tool you can generate one file per markdown tutorial.
Another way could be to integrate claat in the build pipeline and to generate it from the markdown directly, but I think that adds unneccesary overhead, for just 2 tutorials done with the tool.

[Namoshek]

@Namoshek do you have a suggestion how we could integrate them? (According to https://github.com/googlecodelabs/tools "How do I publish my codelabs?" there seems to be a html and markdown option.)

Integrating markdown is probably the easiest solution and could already be possible as well, with some simple instructions in the structure file I think. That doesn't mean using some HTML is an issue though. The only issue is working with legacy AngularJS. 😅

[philippoppel]

Good evening, I think a found a good compromise for a semi interactive tutorial, a challenge in markdown. I thought of a scenario that was a bit similar to T2, but with focus on cascading lookups. I tried to implement a really open and funny format, so the tutorial makes fun to follow along.

Hope you enjoy it

@markus2330 hope this is ok for H2 that I post it here, I wouldnt know where to put it otherwise

Interactive challenge for the KDB Java binding (1).md

[markus2330]

I wouldnt know where to put it otherwise

The idea was to create a PR, similar to #3801

[flo91]

@markus2330 I think this issue should be offered for the FLOSS course.

[markus2330]

Actually the interactive tutorials did not work out so well. I think it is better if we concentrate on validated "standard" tutorials in doc/tutorials.

After 1.0 we can reconsider, then validation isn't so important anymore, as 1.0 gives you guarantees that some things won't change.