You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beam.apache.org by Kenneth Knowles <kl...@google.com> on 2018/06/07 20:23:18 UTC
[DISCUSS] Use Confluence wiki for non-user-facing stuff
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
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Charles Chen <cc...@google.com>.
+1. It would be very helpful to have dev-facing walkthroughs / technical
documentation for relevant aspects of the codebase that aren't user-facing.
On Thu, Jun 7, 2018, 1:23 PM Kenneth Knowles <kl...@google.com> wrote:
> 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
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Mikhail Gryzykhin <mi...@google.com>.
+1 for having a wiki.
One comment:
Is there a specific reason for it to be a Confluence engine?
I know that we use JIRA by Atlassian, but we also utilize Github that has
its own wiki engine that is closer to code and much more lightweight.
I would prefer wiki hosted on Github.
--Mikhail
On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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.
>
> Kenn
>
>
>
> On Mon, Jun 11, 2018 at 2:30 PM Robert Bradshaw <ro...@google.com>
> wrote:
>
>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>>>> echauchot@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
>>>>>>>>>
>>>>>>>>>
>>>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Lukasz Cwik <lc...@google.com>.
I have added all PMC that had an account on the confluence wiki to be
administrators.
Current list of administrators is:
Aljoscha Krettek (aljoscha)
Davor Bonaci (davor)
Daniel Kulp (dkulp)
Gavin (gmcdonald)
Josh Wills (jwills)
Kenneth Knowles (kenn)
Lukasz Cwik (lukecwik)
Jean-Baptiste Onofré (nanthrax)
Robert Bradshaw (rbradshaw)
Stephan Ewen (sewen)
Thomas Weise (thw)
If you need access, reach out to one of the existing administrators or a
PMC to get access.
Also, what should be the list of permissions we grant to non PMC (the list
below enumerates them all)?
AllPagesBlogAttachmentsCommentsRestrictionsMailSpace
ViewDelete OwnAddDeleteAddDeleteAddDeleteAddDeleteAdd/DeleteDeleteExport
Admin
On Mon, Jul 16, 2018 at 9:42 AM Andrew Pilloud <ap...@google.com> wrote:
> 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 <mi...@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 <gr...@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 <ar...@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 <ro...@google.com> wrote:
>>>>
>>>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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 <ro...@google.com>
>>>>> wrote:
>>>>>
>>>>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <
>>>>>>>>>> apilloud@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 <
>>>>>>>>>>>> echauchot@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
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>
>>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Andrew Pilloud <ap...@google.com>.
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 <mi...@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 <gr...@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 <ar...@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 <ro...@google.com> wrote:
>>>
>>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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 <ro...@google.com>
>>>> wrote:
>>>>
>>>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <
>>>>>>>>> apilloud@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 <
>>>>>>>>>>> echauchot@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
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>
>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Mikhail Gryzykhin <mi...@google.com>.
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 <gr...@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 <ar...@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 <ro...@google.com> wrote:
>>
>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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 <ro...@google.com>
>>> wrote:
>>>
>>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>>>>>> echauchot@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
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>
>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Griselda Cuevas <gr...@google.com>.
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 <ar...@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 <ro...@google.com> wrote:
>
> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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 <ro...@google.com>
>> wrote:
>>
>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>>>>> echauchot@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
>>>>>>>>>>
>>>>>>>>>>
>>>>>>
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Alexey Romanenko <ar...@gmail.com>.
+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 <ro...@google.com> wrote:
>
> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <klk@google.com <ma...@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 <robertwb@google.com <ma...@google.com>> wrote:
> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <klk@google.com <ma...@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 <thw@apache.org <ma...@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 <ehudm@google.com <ma...@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/ <https://wiki.apache.org/general/> ? (not sure if that's Confluence)
>
>
> On Fri, Jun 8, 2018 at 10:07 AM Andrew Pilloud <apilloud@google.com <ma...@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 <kedin@google.com <ma...@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 <http://beam.apache.org/> should stay there, not in the wiki;
>
> On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot <echauchot@apache.org <ma...@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/ <https://beam.apache.org/contribute/design-documents/>
>> - Specialized walkthroughs like https://beam.apache.org/contribute/docker-images/ <https://beam.apache.org/contribute/docker-images/>
>> - Best-effort notes that just try to help out like https://beam.apache.org/contribute/intellij/ <https://beam.apache.org/contribute/intellij/>
>> - Docs on in-progress stuff like https://beam.apache.org/documentation/runners/jstorm/ <https://beam.apache.org/documentation/runners/jstorm/>
>> - Expanded instructions for committers, more than https://beam.apache.org/contribute/committer-guide/ <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 <https://github.com/apache/beam/blob/master/sdks/CONTAINERS.md> and https://github.com/apache/beam-site/blob/asf-site/README.md <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
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Robert Bradshaw <ro...@google.com>.
On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles <kl...@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 <ro...@google.com>
> wrote:
>
>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>>>> echauchot@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
>>>>>>>>>
>>>>>>>>>
>>>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Etienne Chauchot <ec...@apache.org>.
Hi all,+1 on targeting different media/sections to different categories of people like Kenn said.Also, IMHO copying what
is in the design docs does not make a lot of sense now that we have then indexed on the website. But putting the
knowledge we (beam devs) have inside our heads and that are not in any document makes a lot of sense to me.
Etienne
Le lundi 11 juin 2018 à 14:39 -0700, Kenneth Knowles a écrit :
> 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.
>
> Kenn
>
>
>
> On Mon, Jun 11, 2018 at 2:30 PM Robert Bradshaw <ro...@google.com> wrote:
> > On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <ec...@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 JIRAbecause 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-guid
> > > > > > > > > > e/
> > > > > > > > > > - BIPs / summaries of collections of JIRA
> > > > > > > > > > - Docs sitting in markdown in the repo like https://github.com/apache/beam/blob/master/sdks/CONTAIN
> > > > > > > > > > ERS.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
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Kenneth Knowles <kl...@google.com>.
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.
Kenn
On Mon, Jun 11, 2018 at 2:30 PM Robert Bradshaw <ro...@google.com> wrote:
> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>>> echauchot@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
>>>>>>>>
>>>>>>>>
>>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Robert Bradshaw <ro...@google.com>.
On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@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 <th...@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 <ap...@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 <
>>>>>> echauchot@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
>>>>>>>
>>>>>>>
>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Scott Wegner <sw...@google.com>.
+1
I don't have much to add to the debate, except to state that Beam currently
has a fragmentation problem for user documentation. I would support
limiting the wiki to non-user focused docs to prevent additional
fragmentation.
We have first-class website pages [1], documentation embedded in Javadocs
[2], and in some cases cloud.google.com/dataflow/docs has more context than
official Beam docs [3].
[1] https://beam.apache.org/documentation/programming-guide/
[2]
https://beam.apache.org/documentation/sdks/javadoc/2.4.0/org/apache/beam/sdk/io/TextIO.html
[3] https://cloud.google.com/dataflow/pipelines/specifying-exec-params
On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <kl...@google.com> wrote:
> Replies in line to keep on the discussion of what we might want to put in
> different venues. But it does sound like there's enough support to at least
> get started on getting our wiki set up to be accessible.
>
> For general context
>
> - Our wiki "exists" here:
> https://cwiki.apache.org/confluence/display/BEAM/
> - It was turned on during incubation:
> https://issues.apache.org/jira/browse/INFRA-11181
>
> I can't seem to edit even though it says anyone can. JB - are you still
> admin? I'd be happy to help.
>
> On Fri, Jun 8, 2018 at 12:45 PM Robert Bradshaw <ro...@google.com>
> wrote:
>
>> The use of wiki vs. docs vs. the (repo-backed) website seems to be one of
>> convenience vs. polish
>>
>
> Wiki vs. docs vs. web site is about other things, too:
>
> - presentation style (slightly different from polish)
> - target audience for each piece of content better (get started
> contributing vs deep dive tutorials)
> - separating large-scale "worlds" of content (vs just different pages on
> the site) to avoid distractions (even polished design docs are a
> distraction for a user-facing site)
>
>
>> , and totally orthogonal to dev vs. user-facing stuff.
>>
>
> User-facing content requires way more polish! But it also has other
> important differences, like expectations, and the relative importance of
> concision vs. comprehensiveness.
>
> I'm not opposed to a wiki, but personally I think a lot of our dev-facing
>> docs (e.g. testing, ptransform style guide, portability overview) benefit
>> from being in a more polished, permanent form (in particular, have been
>> improved going through the code review process).
>>
>
> I do like having review for things that are meant to last. I don't have a
> technical solution in mind for that. I don't think they are mutually
> exclusive anyhow.
>
>
>> Very technical stuff like asf-site/README.md are IMHO best put right next
>> to the sources/artifacts they describe.
>>
>
> Yea the site README is an example that isn't so bad. I do still get a lot
> of questions, because people don't know it is where they should look. The
> worse examples might be the main beam/README.md and sdk/CONTAINERS.md which
> are basically invisible. I think a big problem here is discoverability
> which is very poor for sprinkled docs. It could remain poor on the wiki if
> we make disjoint pages without good breadcrumb paths, but at least there's
> search.
>
>
> On the flip side, no need to limit the wiki to contributor-focused
>> material.
>>
>
> 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.
>
> Kenn
>
>
>
>
>> On Fri, Jun 8, 2018 at 12:05 PM Thomas Weise <th...@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 <ap...@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 <
>>>>>> echauchot@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
>>>>>>>
>>>>>>>
>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Kenneth Knowles <kl...@google.com>.
Replies in line to keep on the discussion of what we might want to put in
different venues. But it does sound like there's enough support to at least
get started on getting our wiki set up to be accessible.
For general context
- Our wiki "exists" here: https://cwiki.apache.org/confluence/display/BEAM/
- It was turned on during incubation:
https://issues.apache.org/jira/browse/INFRA-11181
I can't seem to edit even though it says anyone can. JB - are you still
admin? I'd be happy to help.
On Fri, Jun 8, 2018 at 12:45 PM Robert Bradshaw <ro...@google.com> wrote:
> The use of wiki vs. docs vs. the (repo-backed) website seems to be one of
> convenience vs. polish
>
Wiki vs. docs vs. web site is about other things, too:
- presentation style (slightly different from polish)
- target audience for each piece of content better (get started
contributing vs deep dive tutorials)
- separating large-scale "worlds" of content (vs just different pages on
the site) to avoid distractions (even polished design docs are a
distraction for a user-facing site)
> , and totally orthogonal to dev vs. user-facing stuff.
>
User-facing content requires way more polish! But it also has other
important differences, like expectations, and the relative importance of
concision vs. comprehensiveness.
I'm not opposed to a wiki, but personally I think a lot of our dev-facing
> docs (e.g. testing, ptransform style guide, portability overview) benefit
> from being in a more polished, permanent form (in particular, have been
> improved going through the code review process).
>
I do like having review for things that are meant to last. I don't have a
technical solution in mind for that. I don't think they are mutually
exclusive anyhow.
> Very technical stuff like asf-site/README.md are IMHO best put right next
> to the sources/artifacts they describe.
>
Yea the site README is an example that isn't so bad. I do still get a lot
of questions, because people don't know it is where they should look. The
worse examples might be the main beam/README.md and sdk/CONTAINERS.md which
are basically invisible. I think a big problem here is discoverability
which is very poor for sprinkled docs. It could remain poor on the wiki if
we make disjoint pages without good breadcrumb paths, but at least there's
search.
On the flip side, no need to limit the wiki to contributor-focused
> material.
>
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.
Kenn
> On Fri, Jun 8, 2018 at 12:05 PM Thomas Weise <th...@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 <ap...@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 <ec...@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
>>>>>>
>>>>>>
>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Robert Bradshaw <ro...@google.com>.
The use of wiki vs. docs vs. the (repo-backed) website seems to be one of
convenience vs. polish, and totally orthogonal to dev vs. user-facing
stuff.
I'm not opposed to a wiki, but personally I think a lot of our dev-facing
docs (e.g. testing, ptransform style guide, portability overview) benefit
from being in a more polished, permanent form (in particular, have been
improved going through the code review process). Something like the list of
design docs less so. Very technical stuff like asf-site/README.md are IMHO
best put right next to the sources/artifacts they describe.
On the flip side, no need to limit the wiki to contributor-focused
material.
On Fri, Jun 8, 2018 at 12:05 PM Thomas Weise <th...@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 <ap...@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 <ec...@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
>>>>>
>>>>>
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Thomas Weise <th...@apache.org>.
+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 <ap...@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 <ec...@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
>>>>
>>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Udi Meiri <eh...@google.com>.
(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 <ap...@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 <ec...@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
>>>
>>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Andrew Pilloud <ap...@google.com>.
+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 <ec...@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
>>
>>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Anton Kedin <ke...@google.com>.
+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 <ec...@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
>
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Etienne Chauchot <ec...@apache.org>.
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 JIRAbecause 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
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Kenneth Knowles <kl...@google.com>.
Yup, I'm "kenn". Thanks!
To the thread - if you want write access, please ask. Committers should
certainly have it (but I'll do it lazily) and beyond that I think is up for
discussion.
Kenn
On Mon, Jun 11, 2018 at 5:52 AM Daniel Kulp <dk...@apache.org> wrote:
> Neither you nor JB was setup to be able to do anything with the Wiki. I
> just enabled JB and yourself (assume “kenn” is you) to have permission to
> administer the space so you should be able to add other people.
>
> Dan
>
>
>
> On Jun 9, 2018, at 9:57 AM, Kenneth Knowles <kl...@google.com> wrote:
>
> Yea, we have one but it seems to not be set up quite right. JB you are the
> admin from the original incubation. Can you check the permissions? Also
> make some more admins (maybe all the PMC to start with). I would like to
> help out.
>
> https://cwiki.apache.org/confluence/display/BEAM/
> https://issues.apache.org/jira/browse/INFRA-11181
>
>
> Kenn
>
> On Fri, Jun 8, 2018 at 10:12 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
> wrote:
>
>> +1
>>
>> That's funny, because AFAIR, it's what we discussed in the early stage
>> of the project.
>> We can also link wiki pages on the website if we want to provide details.
>> AFAIR, we already have a confluence wiki space for Beam.
>>
>> Regards
>> JB
>>
>> On 07/06/2018 22:23, Kenneth Knowles wrote:
>> > 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
>>
>> --
>> Jean-Baptiste Onofré
>> jbonofre@apache.org
>> http://blog.nanthrax.net
>> Talend - http://www.talend.com
>>
>
> --
> Daniel Kulp
> dkulp@apache.org - http://dankulp.com/blog
> Talend Community Coder - http://coders.talend.com
>
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Daniel Kulp <dk...@apache.org>.
Neither you nor JB was setup to be able to do anything with the Wiki. I just enabled JB and yourself (assume “kenn” is you) to have permission to administer the space so you should be able to add other people.
Dan
> On Jun 9, 2018, at 9:57 AM, Kenneth Knowles <kl...@google.com> wrote:
>
> Yea, we have one but it seems to not be set up quite right. JB you are the admin from the original incubation. Can you check the permissions? Also make some more admins (maybe all the PMC to start with). I would like to help out.
>
> https://cwiki.apache.org/confluence/display/BEAM/ <https://cwiki.apache.org/confluence/display/BEAM/>
> https://issues.apache.org/jira/browse/INFRA-11181 <https://issues.apache.org/jira/browse/INFRA-11181>
>
>
> Kenn
>
> On Fri, Jun 8, 2018 at 10:12 PM Jean-Baptiste Onofré <jb@nanthrax.net <ma...@nanthrax.net>> wrote:
> +1
>
> That's funny, because AFAIR, it's what we discussed in the early stage
> of the project.
> We can also link wiki pages on the website if we want to provide details.
> AFAIR, we already have a confluence wiki space for Beam.
>
> Regards
> JB
>
> On 07/06/2018 22:23, Kenneth Knowles wrote:
> > 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/ <https://beam.apache.org/contribute/design-documents/>
> > - Specialized walkthroughs
> > like https://beam.apache.org/contribute/docker-images/ <https://beam.apache.org/contribute/docker-images/>
> > - Best-effort notes that just try to help out
> > like https://beam.apache.org/contribute/intellij/ <https://beam.apache.org/contribute/intellij/>
> > - Docs on in-progress stuff
> > like https://beam.apache.org/documentation/runners/jstorm/ <https://beam.apache.org/documentation/runners/jstorm/>
> > - Expanded instructions for committers, more
> > than https://beam.apache.org/contribute/committer-guide/ <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 <https://github.com/apache/beam/blob/master/sdks/CONTAINERS.md>
> > and https://github.com/apache/beam-site/blob/asf-site/README.md <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
>
> --
> Jean-Baptiste Onofré
> jbonofre@apache.org <ma...@apache.org>
> http://blog.nanthrax.net <http://blog.nanthrax.net/>
> Talend - http://www.talend.com <http://www.talend.com/>
--
Daniel Kulp
dkulp@apache.org <ma...@apache.org> - http://dankulp.com/blog <http://dankulp.com/blog>
Talend Community Coder - http://coders.talend.com <http://coders.talend.com/>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Sure, let me change the permissions.
Regards
JB
On 09/06/2018 15:57, Kenneth Knowles wrote:
> Yea, we have one but it seems to not be set up quite right. JB you are
> the admin from the original incubation. Can you check the permissions?
> Also make some more admins (maybe all the PMC to start with). I would
> like to help out.
>
> https://cwiki.apache.org/confluence/display/BEAM/
> https://issues.apache.org/jira/browse/INFRA-11181
>
>
> Kenn
>
> On Fri, Jun 8, 2018 at 10:12 PM Jean-Baptiste Onofré <jb@nanthrax.net
> <ma...@nanthrax.net>> wrote:
>
> +1
>
> That's funny, because AFAIR, it's what we discussed in the early stage
> of the project.
> We can also link wiki pages on the website if we want to provide
> details.
> AFAIR, we already have a confluence wiki space for Beam.
>
> Regards
> JB
>
> On 07/06/2018 22:23, Kenneth Knowles wrote:
> > 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
>
> --
> Jean-Baptiste Onofré
> jbonofre@apache.org <ma...@apache.org>
> http://blog.nanthrax.net
> Talend - http://www.talend.com
>
--
Jean-Baptiste Onofré
jbonofre@apache.org
http://blog.nanthrax.net
Talend - http://www.talend.com
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Kenneth Knowles <kl...@google.com>.
Yea, we have one but it seems to not be set up quite right. JB you are the
admin from the original incubation. Can you check the permissions? Also
make some more admins (maybe all the PMC to start with). I would like to
help out.
https://cwiki.apache.org/confluence/display/BEAM/
https://issues.apache.org/jira/browse/INFRA-11181
Kenn
On Fri, Jun 8, 2018 at 10:12 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
wrote:
> +1
>
> That's funny, because AFAIR, it's what we discussed in the early stage
> of the project.
> We can also link wiki pages on the website if we want to provide details.
> AFAIR, we already have a confluence wiki space for Beam.
>
> Regards
> JB
>
> On 07/06/2018 22:23, Kenneth Knowles wrote:
> > 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
>
> --
> Jean-Baptiste Onofré
> jbonofre@apache.org
> http://blog.nanthrax.net
> Talend - http://www.talend.com
>
Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
+1
That's funny, because AFAIR, it's what we discussed in the early stage
of the project.
We can also link wiki pages on the website if we want to provide details.
AFAIR, we already have a confluence wiki space for Beam.
Regards
JB
On 07/06/2018 22:23, Kenneth Knowles wrote:
> 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
--
Jean-Baptiste Onofré
jbonofre@apache.org
http://blog.nanthrax.net
Talend - http://www.talend.com