Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs #263

Merged
merged 9 commits into from
May 29, 2024
Merged

Improve docs #263

merged 9 commits into from
May 29, 2024

Conversation

keyvaann
Copy link
Collaborator

This PR aims to improve docs on RADAR-Kubernetes with focus on contributors and how they can help to improve RADAR-Kubernetes.
It also tries to answer to following questions:

  • How to create a simple kubernetes environment
  • base.yaml vs production.yaml vs values files: What configuration goes where?
  • Why do we have the individual helm scripts (i.e. 20-fitbit.yaml), are they meant to be individual modules? must they be installed in order? Does anything break if I run them out of order?

@keyvaann keyvaann mentioned this pull request May 21, 2024
4 tasks
Copy link
Contributor

@Bdegraaf1234 Bdegraaf1234 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great, but its an extension of our existing docs and I think one particular problem is that

  • It gives the impression that you need an incredible amount of pre-existing knowledge to set up a cluster, while simultaneously saying: you only need to run 2 commands.
  • It is very extensive, but I would not know to look here if I for example am interested in checking if kafka topics are loaded (something I learned how to do while reviewing this documentation.

I think what we need to resolve these is:

  • A quickstart guide, which just a list of commands and links to this document.
  • That we start to make pages in confluence whenever we come up with questions, and write the answer there with a link to the documentation. That way we have a way to index this documentation in a more granular and practical way.

CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
@Bdegraaf1234
Copy link
Contributor

Bdegraaf1234 commented May 21, 2024

Added some minor spelling suggestions, and a link, otherwise, LGTM

@keyvaann
Copy link
Collaborator Author

keyvaann commented May 22, 2024

It gives the impression that you need an incredible amount of pre-existing knowledge to set up a cluster, while simultaneously saying: you only need to run 2 commands.

I've updated the docs and mention that you can start with 2 commands but you really need the knowledge in order to be able to fully utilize the tools.

It is very extensive, but I would not know to look here if I for example am interested in checking if kafka topics are loaded (something I learned how to do while reviewing this documentation.

I saw it for the first time when I was revisiting the document as well, a document index might help, but it is also gonna become a giant list so I don't know how much it will be helpful.

A quickstart guide, which just a list of commands and links to this document.

Maintaining a shorter version of this document might add some extra overhead, we can provide links to essential sections but scrolling through the document shouldn't take a long time.

That we start to make pages in confluence whenever we come up with questions, and write the answer there with a link to the documentation. That way we have a way to index this documentation in a more granular and practical way.

This can be done, just need to be aware of it and actively do it.

@keyvaann
Copy link
Collaborator Author

@yatharthranjan @mpgxvii feel free to comment if you think there is anything that we can improve.

@keyvaann keyvaann merged commit 9273f13 into dev May 29, 2024
6 checks passed
@keyvaann keyvaann deleted the improve-docs branch May 29, 2024 06:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants