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.


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


-- Peter

Reply via email to