I think ultimately: until the docs a clearly available on the Beam site itself, it's not documentation. See also, design docs, previous emails, and similar.
On Mon, Dec 12, 2022, 6:07 PM Andrew Pilloud via dev <dev@beam.apache.org> wrote: > I believe the previous iteration was here: > https://lists.apache.org/thread/3o8glwkn70kqjrf6wm4dyf8bt27s52hk > > The associated docs are: > https://s.apache.org/beam-io-api-standard-documentation > https://s.apache.org/beam-io-api-standard > > This is missing all the relational stuff that was in those docs, this > appears to be another attempt starting from the beginning? > > Andrew > > > On Mon, Dec 12, 2022 at 9:57 AM Alexey Romanenko <aromanenko....@gmail.com> > wrote: > >> Thanks for writing this! >> >> IIRC, the similar design doc was sent for review here a while ago. Is >> this just an updated version and a new one? >> >> — >> Alexey >> >> On 11 Dec 2022, at 15:16, Herman Mak via dev <dev@beam.apache.org> wrote: >> >> Hello Everyone, >> >> *TLDR* >> >> Should we adopt a set of standards that Connector I/Os should adhere to? >> Attached is a first version of a Beam I/O Standards guideline that >> includes opinionated best practices across important components of a >> Connector I/O, namely Documentation, Development and Testing. >> >> *The Long Version* >> >> Apache Beam is a unified open-source programming model for both batch and >> streaming. It runs on multiple platform runners and integrates with over 50 >> services using individually developed I/O Connectors >> <https://beam.apache.org/documentation/io/connectors/>. >> >> Given that Apache Beam connectors are written by many different >> developers and at varying points in time, they vary in syntax style, >> documentation completeness and testing done. For a new adopter of Apache >> Beam, that can definitely cause some uncertainty. >> >> So should we adopt a set of standards that Connector I/Os should adhere >> to? >> Attached is a first version, in Doc format, of a Beam I/O Standards >> guideline that includes opinionated best practices across important >> components of a Connector I/O, namely Documentation, Development and >> Testing. And the aim is to incorporate this into the documentation and to >> have it referenced as standards for new Connector I/Os (and ideally have >> existing Connectors upgraded over time). If it looks helpful, the immediate >> next step is that we can convert it into a .md as a PR into the Beam repo! >> >> Thanks and looking forward to feedbacks and discussion, >> >> [PUBLIC] Beam I/O Standards >> <https://docs.google.com/document/d/1BCTpSZDUjK90hYZjcn8aAnPd9vuRfj8YU1j3mpSgRwI/edit?usp=drive_web> >> >> Herman Mak | Customer Engineer, Hong Kong, Google Cloud | >> herman...@google.com | +852-3923-5417 <+852%203923%205417> >> >> >> >>
