docs: Improve docs

[alexec]

Signed-off-by: Alex Collins [email protected]

As a reviewer, I don't expect you to open and examine every single file because there are too many. Instead I only expect provide high-level feedback:

(a) Are you happy with the problems and solution below? What should be done different?
(b) How does the site look to you? What would you change?

---

Comments section:

Problem

Engineers are submitting PRs that have not been tested, listed, or had code generation run. This wastes both theirs and the reviewers time resolving, and delaying the PR merge.

Solution

Install a Git pre-commithook that complain if make pre-commit -B and make test have not been run in the last 15m.

Problem

Users often submit PRs that break the docs. This is because they are not checked by CI, and not easy to test locally. These breakages escape into master. Commonly this results in missing docs, or docs that look wrong. These typically need to be fixed by a maintainer.

Solution

Build the docs on CI so (a) the build fails if the docs are broken and the PR cannot be merged (b) the PR reviewer can check them prior to merge.

This includes:

• Spell check
• Broken link check
• Lint

Problem

Users are struggling to get started, and generally dislike the docs.

Documentation is not much user friendly. Am trying to use workflow plugin feature from yesterday. But the examples provided is not giving me any solid direction.

The documentation is difficult to find things in, and it is a lot of trial and error. The linter needs to be better when using templateRef and not require me to first apply the templates to k8s and then realise something is wrong

Unfortunately the current documentation makes on boarding difficult, the examples are good but not flexible enough. Workflow definitions need to be refactored between different execution mode and requires understanding implementation details including how it'll leverage Kubernetes primitives. To create an efficient DAG based workflow with Emissary executor is not trivial while the error messages are rarely useful

Improvement in the documentation and specifically an always up-to-date API documentation would be great :)

Documentation/blog posts with real examples, applications, best practices. Documentation generally, it's good but I've found some rough spots. My team would love a better Pythonic client for people who aren't k8s nerds -- we just started playing with hera but they're also eyeballing Prefect.

Enhance SSO documentation, add more examples for RBAC rules, clarify where ServiceAccounts and RoleBindings need to be created, etc.

The documentation is spartan. Examples would be find.

documentation and samples on Events and Workflow interactions

Better documentation with full CI/CD flow examples

... Better documentation of how to get up and running with common scenarios. Better templates out-of-the box for common tasks like building kaniko images, gradle builds etc.. with more realistic examples (not just a bunch of whalesay examples -- but rather real-life uses). Documentation more oriented to what the user will need to do rather than just concepts. Even the catakoda tutorials are just a bunch of whalesay...there's a big gap between that and actually using it for more practical things...

Documentation looks bad and outdated.

Solution

• Include the "docs by example". This was missing.
• Restructured and re-ordered the navigation.
• Re-write some parts.
• Removed duplicate or out-of-date information.
• Updated the theme.
• Add comments section to get more feedback.

ℹ️ This PR is pushed to origin rather than a fork because Github Actions will not run changed workflows on forks.

[alexec]

run on PRs

[alexec]

defunct targets that should never be run

[alexec]

clearer success/failure warnings

[alexec]

defunct