Refactor example docs - Githubissues

davidkornel commented 1 month ago

WIP

This PR aims to refactor the documentation of the examples. We can remove some redundant text by referring to existing sections of the official documentation under the /docs directory. The PR itself aims to figure out a better format for current/future examples to improve the user experience. Less reading means faster deployment. However, this takes away some information that reaches the users as they tend to skip referred docs. Also, I'm afraid users will lose it if they need to navigate between multiple docs.

Note, that I tried to shorten the length of the example as much as possible, so we would have a starting point.

TODO:

[x] TLS.md Section ### If you have your own domain
[x] Move kurrento to the end of the list in all example listings.
[x] Refactor all other examples.
[x] add TLS.md to readthedocs (edit the mkdocs.yml)
[x] Revert this commit
[x] Fix blockquote syntax
[x] Add elixir example from #162

Questions to figure out:

Separate TLS.md doc in the examples directory:
- Should we keep it there?
- Should we expand it by including something I missed?
- What else should we include in the troubleshooting section?
Troubleshooting doc in general (not just TLS)
- This might worth another issue/PR
STUNner install guide
- Although, it makes sense to point to the INSTALL.md guide, it feels weird to remove those two commands just to include a "go there to find out" text. WDYT?

rg0now commented 1 month ago

Thanks, this is really cool. Minor points:

As per the TLS docs: I dunno a better place either so let's just leave it where it is now.
Kurento: it seems to still be the first one on the list, isn't it?
Rest: do you intend to rewrite the rest of the tutorials TLS-wise too? I'd love to have them consistent

davidkornel commented 1 month ago

One additional TODO:

[ ] add TLS.md to readthedocs (edit the mkdocs.yml)

@levaitamas I'm not sure if I should include it in the examples section or make it top-level like all the other larger documents. What do you say?

levaitamas commented 1 month ago

One additional TODO:

[ ] add TLS.md to readthedocs (edit the mkdocs.yml)

@levaitamas I'm not sure if I should include it in the examples section or make it top-level like all the other larger documents. What do you say?

Since it begins as This documentation sums up the TLS and certificate issues you will encounter deploying the examples., I would put it to the top of examples with a title: Configuring TLS for examples or sth like that. wdyt?

davidkornel commented 1 month ago

Mediasoup and livekit demos done. mediasoup arch fig missing

davidkornel commented 1 month ago

Jitsi done

davidkornel commented 1 month ago

@levaitamas @rg0now Could you give me a review here? I refactored everything or at least most things. Do you see anything that's missing or should be worked on?

TODO add elixir demo from pr #162

levaitamas commented 1 month ago

@levaitamas @rg0now Could you give me a review here? I refactored everything or at least most things. Do you see anything that's missing or should be worked on?

TODO add elixir demo from pr #162

Great work! Added some minor suggestions, otherwise LGTM.

davidkornel commented 1 month ago

@rg0now @levaitamas please review once more.

levaitamas commented 1 month ago

Excellent work, @davidkornel ! I love how you improve it with each iteration. I added some minor comments.

davidkornel commented 4 weeks ago

Hi @rg0now @levaitamas I've included a skip install crds section in the INSTALL.md file. Please take a look and merge if it looks good.

l7mp / stunner

Refactor example docs #164