ReggieCarey commented on issue #673:
URL: https://github.com/apache/camel-kamelets/issues/673#issuecomment-1006743329
I'm glad this issue has sparked a lot of conversation. Consider this some
documentation feedback.
1) The user community can't help with the documentation if we have no clue
as to how the code works or how it was intended to work.
2) The links to the kamelet code in the kameletbinding docs usually end up
at a GitHub 404 page.
3) When the links do work, its generally to a yaml file instead of the
underlying code that someone could explore to improve the documentation.
4) The kameletbinding documentation has been largely untouched for at least
6 months - as noted its autogenerated.
Camel-K developers: You've done an excellent job with the product. I should
point out that you'll get much more constructive feedback and increased usage
if you bring the documentation up to minimum viable product level. The user
community would love to provide constructive feedback but we are working with
what appears to be a lot of barriers to success and its due primarily to not
being able to understand how these yaml files (KameletBindings) can be used to
get something done. I'll say it again
```
steps:
- ref:
kind: Kamelet
apiVersion: camel.apache.org/v1alpha1
name: insert-field-action
properties:
field: The Field
value: The Value
```
is not adequate documentation especially for a product that boasts releasing
version 3.11.5 on 31 Dec 2021. But the above is ALL the documentation there is
on this capability. Disheartening as it is to hear, the documentation sucks.
What are appropriate values for "field"? What are legal values for "value"?
Is there a way to pull values from the cloud event headers? Is there a syntax
you're abiding by to specify where in a json payload the 'value' will be
placed? Is there a templating tool to bring some intelligence to "The Field"
and "The Value" strings?
Can I pull values from previous steps of the kameletbinding? If so, how?
Is there more to the syntax than what is shown in the KameletBinding
exemplars? If so, where is it documented?
What can we do? What functionality is present?
What can we not do? What functionality is missing or broken?
Basically, if the feature is not complete, please help us help you. Tell us
what's missing, what's broken, what's planned. Include a link in the
documentation for the feature if not to the specific code implementing the
feature, then at least to the repo containing the code.
A note on your documentation audience:
Users coming to Kamelets from a Knative/CloudEvent/Kamel Operator
perspective interact with your product via resources deployed into a K8s
cluster. Listing language specific dependencies in this scenario is a bad code
smell. What value is there in telling your audience about your various Java
dependencies for your code? It may be of value to people writing more in-depth
camel integrations or raw custom kamelets but in general your implementation
details should not be a concern to people consuming the solution at the K8s
integration tier. Does any of that dependency info in the docs result in
something actionable by camel-k users?
I submit that your documentation should focus on how to use all of the nifty
things you've built into those Kamelets used in KameletBinding files (the
semantics) instead of just what makes a syntactically correct yaml file.
With respect,
Reggie
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
