Your doc looks good to me. It looks like only one question remains: should it be a Confluence or Github wiki. I see other Apache projects using both, so it seems like either one is possible with support of the Beam community. It might be time to call a vote on this?
Andrew On Fri, Jul 13, 2018 at 9:14 PM Mikhail Gryzykhin <mig...@google.com> wrote: > Hello everyone it's Mikhail and I'm here to revive this long-sleeping > thread. > > I have summarized discussion above into a design/proposal document > <https://docs.google.com/document/d/1qLojdA6GheKf0PVl1A1uip3D2JTk9jQroUKuxriBcfY> > . > > The initial proposal is what I consider the best approach, so it is open > for change. > > Please comment on following topics: > 1. Another engines you have in mind. > 2. If you have access to configure corresponding engine > 3. General ideas. > > Since this is a long-desired change, please, be active. > > --Mikhail > > Have feedback <http://go/migryz-feedback>? > > > On Tue, Jun 12, 2018 at 5:24 PM Griselda Cuevas <g...@google.com> wrote: > >> >> Hi Everyone, >> >> >> (a) should we do it? -- I like the idea of having a wiki, yes. Mainly to >> differentiate the documentation we cater to users and the one we cater to >> contributors. For things like user examples, and more demo-y content, I'd >> suggest we still host it in the Website. >> >> (b) what should go there? -- The ultimate purpose of the wiki should be >> to host everything needed to a) get started (with official documentation) >> and b) how to get the most out of Beam (here is where I see things like >> what Robert suggested could fit, tips, tricks and other cool things created >> by and for our contributors.) >> >> (c) what should not go there? -- Any demos, examples or showcases. I >> think that material should be either embedded or linked (listed) in the >> website. >> >> Tu summarize, I'd like to see the wiki to be a knowledge collection for* >> people who contribute* to the project and the website the collection of >> information that allows *someone to make the decision to use Beam* (or >> join the community). >> >> When we are ready to vote on the creation of a wiki, I'd like to propose >> that the first thing we document there is the Beam Improvement plan along >> side with a concrete "Get Started Contributing to Beam" cheatsheet. >> >> WDYT? >> >> >> On Tue, 12 Jun 2018 at 09:34, Alexey Romanenko <aromanenko....@gmail.com> >> wrote: >> >>> +1 for having Wiki for devs and users. >>> >>> Even though editing interface is not so native and obvious (comparing to >>> Google docs), but, at least, it will be already put in one place and should >>> be much more easy to search and discover. >>> >>> The only my concern about Wiki (based on using it in other different >>> projects) that, in course of time, the information becomes outdated and >>> weak structured which makes this not so valuable and even deceptive. >>> >>> WBR, >>> Alexey >>> >>> On 12 Jun 2018, at 18:01, Robert Bradshaw <rober...@google.com> wrote: >>> >>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <k...@google.com> wrote: >>> >>>> OK, yea, that all makes sense to me. Like this? >>>> >>>> - site/documentation: writing just for users >>>> - site/contribute: basic stuff as-is, writing for users to entice >>>> them, links to the next... >>>> - wiki/contributors: contributors writing just for each other >>>> >>>> And you also have >>>> >>>> - wiki/users: users writing for users >>>> >>>> That's interesting. >>>> >>> >>> Yep. We don't have to start wiki/users right away, but it could be >>> useful down the line. >>> >>> >>> >>>> On Mon, Jun 11, 2018 at 2:30 PM Robert Bradshaw <rober...@google.com> >>>> wrote: >>>> >>>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <k...@google.com> wrote: >>>>> >>>>> >>>>>> I disagree strongly here - I don't think the wiki will have >>>>>> appropriate polish for users. Even if carefully polished I don't think >>>>>> the >>>>>> presentation style is right, and it is not flexible. Power users will >>>>>> find >>>>>> it, of course. >>>>>> >>>>> >>>>> I wasn't imagining a wiki as a platform for developers to author >>>>> documentation, rather a place for users to author content for other users >>>>> (tips and tricks, handy PTransforms, etc.) at a much lower bar than >>>>> expecting users to go in and update our documentation. I agree with the >>>>> goal of not (further) fragmenting our documentation. >>>>> >>>>> As for mixing contributor vs. user information on the same site, I >>>>> think it's valuable to have some integration and treat the two as a >>>>> continuum (after all, our (direct) users are already developers) and >>>>> consider it an asset to have a "contribute" heading right in the main >>>>> site. >>>>> (Perhaps, if it's confusing, we could move it all the way to the right.) I >>>>> don't think we'll be doing ourselves a favor by blinding copying all the >>>>> existing docs to a wiki. That being said I think it makes sense to start >>>>> playing with using a wiki, and see how much value that adds on top of what >>>>> we already have. >>>>> >>>>> >>>>>> >>>>>> >>>>>>> On Fri, Jun 8, 2018 at 12:05 PM Thomas Weise <t...@apache.org> wrote: >>>>>>> >>>>>>>> +1 most of the contributor material could live on Wiki and there it >>>>>>>> will be easier to maintain (perhaps the lower bar for updates will >>>>>>>> lead to >>>>>>>> more information and increased maintenance). Contribution policy >>>>>>>> related >>>>>>>> material should remain on the website and go through proper >>>>>>>> review/versioning. >>>>>>>> >>>>>>>> >>>>>>>> On Fri, Jun 8, 2018 at 11:44 AM, Udi Meiri <eh...@google.com> >>>>>>>> wrote: >>>>>>>> >>>>>>>>> (a) Yes. >>>>>>>>> (b) I'm interested in putting documentation for contributors >>>>>>>>> there. (test triage guide, precommit and postcommit guidelines, >>>>>>>>> processes, >>>>>>>>> etc.) >>>>>>>>> It'd be faster than having to go through the motions of a github >>>>>>>>> pull request and a review process. >>>>>>>>> (c) Anything that goes to a wide audience, such as SDK users. That >>>>>>>>> would need review. >>>>>>>>> >>>>>>>>> Also, have you looked at https://wiki.apache.org/general/ ? (not >>>>>>>>> sure if that's Confluence) >>>>>>>>> >>>>>>>>> >>>>>>>>> On Fri, Jun 8, 2018 at 10:07 AM Andrew Pilloud < >>>>>>>>> apill...@google.com> wrote: >>>>>>>>> >>>>>>>>>> +1 It would be really nice to have a lightweight place to share >>>>>>>>>> that is more searchable then random Google docs. >>>>>>>>>> >>>>>>>>>> Andrew >>>>>>>>>> >>>>>>>>>> On Fri, Jun 8, 2018 at 9:35 AM Anton Kedin <ke...@google.com> >>>>>>>>>> wrote: >>>>>>>>>> >>>>>>>>>>> +1 >>>>>>>>>>> >>>>>>>>>>> (a) we should; >>>>>>>>>>> (b) I think it will be a good place for all of the things you >>>>>>>>>>> list; >>>>>>>>>>> (c) introductory things, like "getting started", or "programming >>>>>>>>>>> guide" that people not deeply involved in the project would expect >>>>>>>>>>> to find >>>>>>>>>>> on beam.apache.org should stay there, not in the wiki; >>>>>>>>>>> >>>>>>>>>>> On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot < >>>>>>>>>>> echauc...@apache.org> wrote: >>>>>>>>>>> >>>>>>>>>>>> Hi Kenn, >>>>>>>>>>>> I'm +1 of course. I remember that you and I and others >>>>>>>>>>>> discussed in a similar thread about dev facing docs but it got >>>>>>>>>>>> lost at some >>>>>>>>>>>> point in time. >>>>>>>>>>>> IMHO >>>>>>>>>>>> >>>>>>>>>>>> I would add >>>>>>>>>>>> - runners specifics (e.g. how runners implement state or timer, >>>>>>>>>>>> how they split data into bundles, etc...) >>>>>>>>>>>> - probably putting online the doc I did for nexmark that >>>>>>>>>>>> summarizes the architecture and pseudo code of the queries >>>>>>>>>>>> (because some >>>>>>>>>>>> are several thousand lines of code). I often use it to recall what >>>>>>>>>>>> a given >>>>>>>>>>>> query does. >>>>>>>>>>>> >>>>>>>>>>>> I would remove >>>>>>>>>>>> - BIPs / summaries of collections of JIRA >>>>>>>>>>>> because it is hard to maintain and will end up being out of >>>>>>>>>>>> date I think. >>>>>>>>>>>> >>>>>>>>>>>> Etienne >>>>>>>>>>>> >>>>>>>>>>>> Le jeudi 07 juin 2018 à 13:23 -0700, Kenneth Knowles a écrit : >>>>>>>>>>>> >>>>>>>>>>>> Hi all, >>>>>>>>>>>> >>>>>>>>>>>> I've been in half a dozen conversations recently about whether >>>>>>>>>>>> to have a wiki and what to use it for. Some things I've heard: >>>>>>>>>>>> >>>>>>>>>>>> - "why is all this stuff that users don't care about here?" >>>>>>>>>>>> - "can we have a lighter weight place to put technical >>>>>>>>>>>> references for contributors" >>>>>>>>>>>> >>>>>>>>>>>> So I want to consider as a community starting up our wiki. >>>>>>>>>>>> Ideas for what could go there: >>>>>>>>>>>> >>>>>>>>>>>> - Collection of links to design docs like >>>>>>>>>>>> https://beam.apache.org/contribute/design-documents/ >>>>>>>>>>>> - Specialized walkthroughs like >>>>>>>>>>>> https://beam.apache.org/contribute/docker-images/ >>>>>>>>>>>> - Best-effort notes that just try to help out like >>>>>>>>>>>> https://beam.apache.org/contribute/intellij/ >>>>>>>>>>>> - Docs on in-progress stuff like >>>>>>>>>>>> https://beam.apache.org/documentation/runners/jstorm/ >>>>>>>>>>>> - Expanded instructions for committers, more than >>>>>>>>>>>> https://beam.apache.org/contribute/committer-guide/ >>>>>>>>>>>> - BIPs / summaries of collections of JIRA >>>>>>>>>>>> - Docs sitting in markdown in the repo like >>>>>>>>>>>> https://github.com/apache/beam/blob/master/sdks/CONTAINERS.md >>>>>>>>>>>> and https://github.com/apache/beam-site/blob/asf-site/README.md >>>>>>>>>>>> (which will soon not be a toplevel README) >>>>>>>>>>>> >>>>>>>>>>>> What do you think? >>>>>>>>>>>> >>>>>>>>>>>> (a) should we do it? >>>>>>>>>>>> (b) what should go there? >>>>>>>>>>>> (c) what should not go there? >>>>>>>>>>>> >>>>>>>>>>>> Kenn >>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>> >>>
