Hi,
The descriptions of components, languages, data formats, etc. in Camel
catalog currently use several inconsistent styles. I wonder whether we
could agree on some common style?
Here an attempt to describe the current state by roughly classifying the
styles and giving some examples. A common style proposal is below.
= "Copy the title" style:
* A Camel GraphQL Component
* Camel Cron Component
= "What it does" style:
* Bridging Eclipse MicroProfile Health with Camel health checks
* Camel metrics exposed with Eclipse MicroProfile Metrics
* Communicates with OData 4.0 services using Apache Olingo OData API.
= "Component for <purpose>" style
* Component for communicating with MQTT message brokers using Eclipse
Paho MQTT Client.
* Component for working with documents stored in MongoDB database.
= "For <purpose>" style
* For calling out to external HTTP servers using Apache HTTP Client 4.x.
* For reading/writing from/to Infinispan distributed key/value store and
data grid.
* For uploading downloading and managing files folders groups
collaborations etc on box DOT com.
= "<title> <kind> is used for <purpose>" style
* JacksonXML data format is used for unmarshal a XML payload to POJO or
to marshal POJO back to XML payload.
* JSon data format is used for unmarshal a JSon payload to POJO or to
marshal POJO back to JSon payload.
= "<title> using <technology>"
* Camel WebSocket using JSR356 (javax)
* Circuit Breaker EIP using Netflix Hystrix
* Distributed tracing using OpenTracing
I think the following basic principles might be useful when trying to
come up with a common style:
(i) Shorter is better. Less/shorter words are faster to read and faster
to understand
(ii) An application of (i): Leave out words and information available
elsewhere in the Catalog record. Esp. do not repeat the title and kind
(component, language, ...) because they are clear from the context. The
same holds for the word "Camel".
(iii) Concentrate on functionality (what it does), because that's what
most users want to know.
"What it does" style seems to be the best match. From the several
flavors, I think the shortest with the plain (imperative) form of the
verb should be prefered - e.g.
new: Unmarshal an XML payload to POJO or marshal a POJO back to XML.
old: JacksonXML data format is used for unmarshal a XML payload to POJO
or to marshal POJO back to XML payload.
The same information, but 6 (~1/3) words less.
WDYT?
Disclaimer: my motivation for this proposal is driven by the fact that
I'd like to re-use the catalog data when scaffolding new Camel Quarkus
extensions, esp. generating pieces of Camel Quarkus documentation and
for generating extension metadata for code.quarkus.io
Thanks,
-- Peter
