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 >>>>>>>>>>> >>>>>>>>>>> >>>>>>> >>
