Guide development: static vs more dynamic

[cmoulliard]

I'm wondering if we should develop the guide's content using a more traditional approach/way where we describe the step-by-step instructions with snippet codes using a static format (markdown, asciidoctor) OR if we must enhance it using by example katacoda

Even if more work will be required for developing a step-by-step guide targeting katacoda, it offers with run command a very intuitive way to play with the technology, which is zero-error, can also avoid that we explain within the guide how to be Cloud Ready, jow to setup f-m-p, ... As we control what is deployed on openshift, we have better control

Guide is designed as a collection of steps with code - snippet

Example of scenario : https://github.com/katacoda/scenario-example/tree/master/scenario

1. Snippet code can be executed with katacoda openshift's terminal if you add {{execute}} tag

The library _hyperkube_ allows you to launch the different components. The first component is the API server. The API processes requests from the master and store information in the etcd cluster.
`
docker run -d --name=api \
    --net=host --pid=host --privileged=true \
    gcr.io/google_containers/hyperkube:v1.1.2 \
    /hyperkube apiserver \
    --insecure-bind-address=0.0.0.0 \
    --service-cluster-ip-range=10.0.0.1/24 \
    --etcd_servers=http://127.0.0.1:4001 \
    --cluster_name=kubernetes --v=2
`{{execute}}

or executed and copied to editor (if you use <pre></pre>)

The following snippet can be copied into the editor:

<pre class="file" data-filename="app.js" data-target="replace">var http = require('http');
var requestListener = function (req, res) {
  res.writeHead(200);
  res.end('Hello, World!');
}

var server = http.createServer(requestListener);
server.listen(3000, function() { console.log("Listening on port 3000")});
</pre>

Code can be executed with the syntax `node app.js`{{execute}}

WDYT : @lincolnthree, @gytis, @metacosm, @geoand ?

E.g. : https://www.katacoda.com/courses/docker/deploying-first-container

[geoand]

I think it would be very interesting to explore Katacoda for some of the guides.

However I am not sure that it's suited for all the stuff we want to showcase. For example the http guide that @metacosm is writing as well as the integration testing guide I am writing are more about explaining things in depth that actually showing stuff running.
In such cases we are actually trying to explain why FMP is configured the way it is, why Arquillian is configured in such a manner, why all various pieces work together to provide a great experience.
Such in depth explanations are solely lacking in any kind of documentation we have seen and we are uniquely qualified to explain this black magic :)

So in my mind it's not a question of one or the other, I believe we can very well do both.
Use Katacoda for guides were we want to show things actually working and use the standard asciidoc format for in depth explanation guides

[metacosm]

To be honest, I think the boosters could be developed as Katacoda example instead of using launcher as their scope is quite small and Katacoda would be well suited to show the examples they demonstrate running easily. ;)
For the guides, I agree that the focus is more on in-depth explanations rather than actually running things. The in-depth parts, though, are not really specific to a particular booster so they might actually be more appropriate as part of a "cloud-native reference development guide", while showing the boosters and getting the users the quick wins that will get them hooked to the platform might be better suited for a Katacoda tutorial.

[metacosm]

The more I think about it, the more I think documenting the code / deployment parts of the boosters as katacoda lessons is the best way to do it. Then, we can focus on more reference-type documents on the site.

[lincolnthree]

I think this would be fine, though I think we'd still want to make sure whatever we do functions well on the website and keeps users engaged there. E.g. We'll still need guides and instructions on the site that explain what to do with Katacoda.

[metacosm]

Well, the beauty of katacoda (if done well) is that the instructions are right there in the tutorial so it should be self-contained and stand on its own.

[lincolnthree]

Right but how do users find out about what katacoda demos to access in the first place? And etc... we'd want those showcased somewhere on the site, yes?