search

argoproj / argo-cd

Declarative Continuous Deployment for Kubernetes
https://argo-cd.readthedocs.io
Apache License 2.0
17.43k stars 5.3k forks source link

Ongoing effort to refresh user documentation - Invitation to participate! #5635

Open jannfis opened 3 years ago

jannfis commented 3 years ago

Summary

As discussed in one of the recent contributor's meeting, our docs need some love.

This is an umbrella issue to track the efforts and facilitate the collaboration on bringing that overdue refresh to our docs, so that it provides a more user-focused journey and become comprehensive, clear and concise.

Everyone is invited to participate, and this is the invitation

We have started to prototype an proposal and we made it available in the refresh-docs branch in this repository. Also, the latest version of this proposal can be viewed online at https://argo-cd.readthedocs.io/en/refresh-docs/

We need your help in improving our docs.

Where to participate?

The ongoing effort is undertaken in a dedicated branch of the argo-cd repository, and accompanying discussions should take place in this issue.

The branch's name is refresh-docs, and all pull requests should be sent to this branch instead of the master branch. Please note that commits in such PRs should only target paths below the docs/

How to participate?

We are looking for a multitude of opinions and point of views, and there's lots of things on how you can help.

Discuss and improve the structure (journey) of the documentation

The existing documentation is hard to navigate, and things are hard to find without the search function. One thing we want to improve is this journey. Have a look at the current state of the proposal and let us know how to improve. Is something illogical? Could something be better found at a different place of the TOC? Please leave a comment in this issue, so we can start a discussion!

Note: Please do not send PRs changing the TOC and structure before a discussion has taken place, and consent was found.

Fix spelling and grammar issues

Found a typo? Is some grammar bad or could be improved? Send a PR against the refresh-docs branch to fix that :)

Fix logical errors

Documentation is outdated? A broken link? Or plainly wrong in some place? Is it inconsistent with other parts of the docs? Send a PR against the refresh-docs branch to fix that :)

Something missing?

Is there something missing from the current docs? Let us know in a comment to this issue!

Fill the gaps with content

Many of the pages you will see in the current state of the proposal are still blank and need to be filled with actual content. If you think you fully understand a feature, and are proficient enough with the English language to write good technical documentation, send a PR against the refresh-docs branch with your idea of how this gap could be filled. No worries about being 100% error free, we'll hopefully find and fix any typos, grammar deficits and logical errors during the review process. Maybe we'll miss them, too. Anyhow, filling the gaps is much appreciated :)

Please make sure that before sending a PR, the docs can be build correctly using mkdocs. In order to test locally, either install mkdocs locally or use the build-docs target of the Makefile, which builds documentation in a Docker container.

Also, to check whether your documentation looks appropriate, you can check before submitting a PR using mkdocs server (given that mkdocs is installed) or make serve-docs and then point your browser to http://localhost:8000 to view the rendered docs.

jemisonf commented 3 years ago

I had some minor changes I was going to suggest for the Operations and Maintenance section based on looking at the current structure:

I can help out with the first bullet but I don't think I have enough quite enough insight into Argo CD metrics to be helpful with the second one.

jannfis commented 3 years ago 
* "High Availability" isn't the most intuitive name for me for a section that (in the current docs) has a lot to do with scaling. I'm wondering if it would make sense to have separate sections for high availability (specifically oriented towards HA deploys) and scaling (more focused on the stuff that's under ["scaling up" in the current docs](https://argoproj.github.io/argo-cd/operator-manual/high_availability/#scaling-up))

I agree. I think the refresh-docs branch has something about HA deploys here, which we could expand a little.

Then, maybe we can rename High Availability into "Scaling Up" or some more appropriate name. Maybe "Scaling considerations"?

* I think the "Metrics" section in the current docs is only kind of helpful but if it had a list of available prometheus metrics with an explanation for each it would be _really_ useful. There's some amount of metric info in the "scaling up" section but I don't think it's very comprehensive.

Maybe it will be possible to auto-generate Metrics docs from the code, similar to what we do with the CLI commands and options. At least this would ensure the docs would always be up-to-date, but I'm also unsure about. But I do agree that it would be quite useful.

I can help out with the first bullet but I don't think I have enough quite enough insight into Argo CD metrics to be helpful with the second one.

Please, go ahead :)

jemisonf commented 3 years ago

Maybe it will be possible to auto-generate Metrics docs from the code, similar to what we do with the CLI commands and options. At least this would ensure the docs would always be up-to-date, but I'm also unsure about. But I do agree that it would be quite useful.

I found one tool for this that seems kind of useful: https://grafana.com/blog/2019/11/05/metrics-documentation-with-the-metrics2docs-tool/, although it's old and it doesn't look like it's actively maintained. That does seem like the way to go though if it's possible -- maintaining a full list of metrics by hand does not sound like a good time.

joebowbeer commented 3 years ago

The section re. configured vs unconfigured repos is duplicated? https://argo-cd.readthedocs.io/en/refresh-docs/basics/repos/#unconfigured-vs-configured-repositories https://argo-cd.readthedocs.io/en/refresh-docs/basics/repositories/#unconfigured-vs-configured-repositories

kostis-codefresh commented 3 years ago

I think the revised documentation can be improved by adding a top level section called "how-tos" or "common tasks" or something similar that describes repeatable actions for readers who want to get started fast.

Some examples for this task-based section:

The target audience would be developers who are given access to an Argo installation and want to get started as fast as possible without actually becoming experts (i.e. having to read all docs in order from start to finish).

Basically imagine that I work in a big company and at some point an Ops person comes to me and says "Hey we have ArgoCd installed there, feel free to use it". I need a quick way to do what I want with limited time available.

On a related note, see also the concepts/reference/tutorials/guides split at https://documentation.divio.com/introduction/#the-secret (and https://documentation.divio.com/adoption/)

jannfis commented 3 years ago

That's an excellent suggestion @kostis-codefresh and I agree that the documentation lacks concrete tutorials further than the most simple Getting Started one.

joebowbeer commented 3 years ago

Missing is an overview discussing some of the high-level decisions such as bootstrapping versus centralized management (from a management cluster, hub-and-spoke style).

For bootstrapping, there is a lot of context and unwritten knowledge missing. For example, there is a deployments project on GH, which probably should be referenced more, but there is no information or scripts explaining how these deployments were bootstrapped. (Are those deployments in fact bootstrapped? Or is this an example of hub-and-spoke?)

The information that the argo-helm charts are not supported is well-hidden.

todaywasawesome commented 2 weeks ago

@jannfis @kostis-codefresh is this still happening?

There's an open PR to add some docs here but I don't want to merge it since it's in a WIP branch. https://github.com/argoproj/argo-cd/pull/16964 I think that should be up to whoever is working on this project if it's still active.