Move examples to file reference. Add real examples (GitLab, MySql, Wordpress, etc.)

[cdrage]

The examples we currently use: https://github.com/kedgeproject/kedge/tree/master/examples reflect similarly to how we define our artifacts via the file reference doc.

Examples should show-case real-world deployments.
Our "current' examples should be moved to a different "spec" or "file reference" folder.

I suggest we move these examples to /docs/spec or a better-named folder and then add real-world examples such as GitLab, Cassandra, ElasticSearch, etc, similar to: https://github.com/kubernetes/kubernetes/tree/master/examples

[pradeepto]

Good point about adding those examples, I have no strong opinions on where they should reside as long as we have simple examples that help people to learn the concept, configuration and tooling and also have "real world" examples that you are talking about. And these should be clearly pointed out in the readme.

[kadel]

I don't think that examples should reside in /docs/spec. They are examples that have nothing to do with spec. I think that /docs/examples is right place for it

[surajssd]

What @cdrage says also makes sense that we should have examples that show real world examples and what @kadel said also makes that these shortcut specific examples should not be in spec.

I propose that we create following directory structure:

✔ ~/go/src/github.com/kedgeproject/kedge/examples [master L|✚ 34…38] 
17:21 $ tree
.
├── real
│   ├── etherpad
│   │   └── app.yaml
│   ├── gitlab
│   │   └── app.yaml
│   ├── mattermost
│   │   └── app.yaml
│   └── wordpress
│       └── app.yaml
└── usage
    ├── all
    │   ├── db.yaml
    │   ├── README.md
    │   └── web.yaml
    ├── allnomagic
    │   ├── db.yaml
    │   ├── README.md
    │   └── web.yaml
    ├── configmap
    │   ├── db.yaml
    │   ├── README.md
    │   └── web.yaml
    ├── customVol
    │   ├── db.yaml
    │   ├── README.md
    │   └── web.yaml
    ├── envFrom
    │   ├── db.yaml

[kadel]

@kadel said also makes that these shortcut specific examples should not be in spec.

I don't know if I said that :D

I actually thing that spec should contain partial examples (snippets) highlighting how shortcuts are typically used.

Example directory should contain only examples of real applications.
I believe that in the example directory should be only examples that work and make sense.

I would actually remove everything that you have put in 'usage' directory.
Those can be broken into snippets highlighting just important part and be placed to spec document.

[cdrage]

real and usage seems a bit odd.. I'd have to agree with @pradeepto to get the current examples into /docs and put examples such as gitlab, mattermost, etc to /examples

[pradeepto]

I think, I said this in another issue but let me try to phrase this correctly.

We should have two examples:

1. Spec examples. Look at various API documentation. Generally, there is one complete example at the top - showcasing/highlighting the important things and a general overview. Then with every class, method etc are interspersed with small snippets focusing on the method/class etc. Snippets are not often complete examples. Hence these examples are actually part of the spec documentation instead of actual files.
2. Real/complex/big examples showcasing the power of kedge.

I think that is what @kadel is saying exactly that. Hope this clarifies my point.

[kadel]

The first part ("Move examples to file reference") of this is being taken care of in #222

[cdrage]

Examples have mostly been added to http://kedgeproject.org/file-reference/ although, it would be nice to have an #430 examples page.

[cdrage]

I think we can close this now. Anyone else agree @kadel @pradeepto ?