Hi Yes I would like to make those short component descriptions better, especially the ones that just say
Camel support for Foo I like the idea of making the description focus on the main functionality and keep it short. Yes we can sometime leave out the project name as its in the title anyway. Currently all the titles are in the class javadoc mainly, and for others in the pom.xml description. So its a bit of "hunt" to find and update them, but surely go for it. On Mon, Apr 6, 2020 at 3:54 PM Peter Palaga <ppal...@redhat.com> wrote: > > 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 > -- Claus Ibsen ----------------- http://davsclaus.com @davsclaus Camel in Action 2: https://www.manning.com/ibsen2
