Agree* with Romain that versioning is hard to follow and it is "somewhere" but hard to find.
I would further emphasize that design drafts for discussion simply are *not* the same thing as reference documentation. We should surely index our drafts somewhere on the website, but that may lend us a false sense that we have done enough. Once a design has been implemented and baked enough, if it is intended to be referred to later (for example our core APIs) it must be properly documented. Here are some example tickets for porting gdoc drafts to reference documentation: - https://issues.apache.org/jira/browse/BEAM-2360 (runner author guide - done, sketchy, needs update to emphasize portability) - https://issues.apache.org/jira/browse/BEAM-2568 (lateness guide - todo) - https://issues.apache.org/jira/browse/BEAM-2567 (trigger guide - not going to do it until sink triggers) - https://issues.apache.org/jira/browse/BEAM-2472 (state & timers - todo, part of a larger rewrite) Please do file these if/when you find more! Docs that have now been part of Beam for a while and should be migrated soon, off the top of my head: - https://s.apache.org/beam-metrics-api (updated for portability) - https://s.apache.org/beam-fn-api (some of it, anyhow) Docs that are examples of designs that probably need to be proven before writing up: - https://s.apache.org/beam-job-api - https://s.apache.org/beam-mixed-language-pipelines Kenn * The ASF question has been discussed and we are OK there. Design proposals for collaboration do not need to be owned by a PMC account - they are owned by their authors. On Fri, Mar 9, 2018 at 2:35 PM Reuven Lax <re...@google.com> wrote: > I think this has been discussed before. gdocs provides a much better tool > for collaborative editing, and much easier to use than the alternative. It > also provides extremely detailed version tracking. > > However I do think some of your concerns are valid. Rather than eliminate > the use of gdocs, I would propose the following: > > * Every proposal must have an abstract that is sent to the list (not > just a "here is a doc"). The abstract does not need to contain all the gory > details, but must but complete enough to explain what the proposal is about > (and enough to enable good searching) > * We index these abstracts (along with pointers to the associated docs) > on the Beam website. > > Of course using gdocs is never a requirement - you're free to use another > tool for your proposals! I just don't think we should ban useful tools. > > Reuven > > > > On Fri, Mar 9, 2018 at 2:14 PM Romain Manni-Bucau <rmannibu...@gmail.com> > wrote: > >> Hi guys >> >> A lot of design docs are done through gdoc. I see how awesome it is to >> work but @asf it has a few issues - and more bothering, it quickly makes >> the tracking blurry. >> >> Out of my head here are a few issues I see/hit: >> >> - it doesnt happen on the list (even if a mail is sent the content is not >> available) - makes the search kind of harder >> - it is not under asf umbrella I think (is there an asf account or so >> under pmc scope which can track all actions?) >> - versionning is hard to follow or it is not versionned at all >> - it is "somewhere" but very hard to find with common tools (list >> archives, main git, ...) >> >> Therefore I propose to use gdoc for short period of time if you feel it >> better and just integrate designs as sources as well (in asciidoctor to >> have diagrams and all potential syntax or directly the site source but >> inline/not link?). This will fix all but the first issue and even allow to >> comment on PRs/reviews instead of gdoc. >> >> For the first point we can do as for incubator projects and include the >> original content in text form at the end of the mail. Will give enough >> context to find the thread back hopefully. >> >> Wdyt? Anyone else hitting these issues from time to time? >> >>
