Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Lukasz Cwik]

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  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 
> 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
>> 
>> .
>>
>> 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 ?
>>
>>
>> On Tue, Jun 12, 2018 at 5:24 PM Griselda Cuevas  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 
>>> 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  wrote:

 On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  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 
> wrote:
>
>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles 
>> 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 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Andrew Pilloud]

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  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
> 
> .
>
> 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 ?
>
>
> On Tue, Jun 12, 2018 at 5:24 PM Griselda Cuevas  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 
>> 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  wrote:
>>>
>>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  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 
 wrote:

> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Mikhail Gryzykhin]

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

.

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 ?


On Tue, Jun 12, 2018 at 5:24 PM Griselda Cuevas  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 
> 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  wrote:
>>
>> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  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 
>>> wrote:
>>>
 On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  wrote:
>>>
 (a) Yes.

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Griselda Cuevas]

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 
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  wrote:
>
> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  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 
>> wrote:
>>
>>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
>>> 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, 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Alexey Romanenko]

+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  wrote:
> 
> On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  > 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  > wrote:
> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  > 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  > 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  > 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  > 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  > 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  > 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 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Robert Bradshaw]

On Mon, Jun 11, 2018 at 2:40 PM Kenneth Knowles  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 
> wrote:
>
>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
>> 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  wrote:
>>>
 +1

 (a) we should;
 (b) I think it will be a good place for all of the things you list;
 (c) introductory things, like "getting started", or "programming
 guide" that people not deeply involved in the project would expect to 
 find
 on beam.apache.org should stay there, not in the wiki;

 On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot <
 echauc...@apache.org> wrote:

> Hi Kenn,
> I'm +1 of course. I remember that you and I and others discussed
> in a similar thread about dev facing docs but it got lost at some 
> point in
> time.
> IMHO
>
> I would add
> - runners specifics (e.g. how runners implement state or timer,
> how they split data into bundles, etc...)
> - probably putting online the doc I did for nexmark that
> summarizes the architecture and pseudo code of the queries (because 
> some
> are several thousand lines of code). I often use it to recall what a 
> given
> query does.
>
> I would remove
>  - BIPs / summaries of collections of JIRA
> because it is hard to maintain and will end up being out of date I
> think.
>
> Etienne
>
> Le jeudi 07 juin 2018 à 13:23 -0700, Kenneth Knowles a écrit :
>
> Hi all,
>
> I've been in half a dozen conversations recently about whether to
> have a wiki and what to use it for. Some things I've heard:
>
>  - "why is all this stuff that users don't care about here?"
>  - "can we have a lighter weight place to put technical references
> for contributors"
>
> So I want to consider as a community starting up 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Etienne Chauchot]

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  wrote:
> > On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
> > > > > >  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  
> > > > > > > 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 
> > > > > > > >  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 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Mikhail Gryzykhin]

+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  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 
> wrote:
>
>> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
>> 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  wrote:
>>>
 +1

 (a) we should;
 (b) I think it will be a good place for all of the things you list;
 (c) introductory things, like "getting started", or "programming
 guide" that people not deeply involved in the project would expect to 
 find
 on beam.apache.org should stay there, not in the wiki;

 On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot <
 echauc...@apache.org> wrote:

> Hi Kenn,
> I'm +1 of course. I remember that you and I and others discussed
> in a similar thread about dev facing docs but it got lost at some 
> point in
> time.
> IMHO
>
> I would add
> - runners specifics (e.g. how runners implement state or timer,
> how they split data into bundles, etc...)
> - probably putting online the doc I did for nexmark that
> summarizes the architecture and pseudo code of the queries (because 
> some
> are several thousand lines of code). I often use it to recall what a 
> given
> query does.
>
> I would remove
>  - BIPs / summaries of collections of JIRA
> because it is hard to maintain and will end up being out of date I
> think.
>
> Etienne
>
> Le jeudi 07 juin 2018 à 13:23 -0700, Kenneth Knowles a écrit :
>
> Hi all,
>
> I've been in half a dozen conversations recently about whether to
> have a wiki and what to use it for. Some things I've heard:
>
>  - "why is all this 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Kenneth Knowles]

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

> On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
> 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  wrote:
>>
>>> +1
>>>
>>> (a) we should;
>>> (b) I think it will be a good place for all of the things you list;
>>> (c) introductory things, like "getting started", or "programming
>>> guide" that people not deeply involved in the project would expect to 
>>> find
>>> on beam.apache.org should stay there, not in the wiki;
>>>
>>> On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot <
>>> echauc...@apache.org> wrote:
>>>
 Hi Kenn,
 I'm +1 of course. I remember that you and I and others discussed in
 a similar thread about dev facing docs but it got lost at some point in
 time.
 IMHO

 I would add
 - runners specifics (e.g. how runners implement state or timer, how
 they split data into bundles, etc...)
 - probably putting online the doc I did for nexmark that summarizes
 the architecture and pseudo code of the queries (because some are 
 several
 thousand lines of code). I often use it to recall what a given query 
 does.

 I would remove
  - BIPs / summaries of collections of JIRA
 because it is hard to maintain and will end up being out of date I
 think.

 Etienne

 Le jeudi 07 juin 2018 à 13:23 -0700, Kenneth Knowles a écrit :

 Hi all,

 I've been in half a dozen conversations recently about whether to
 have a wiki and what to use it for. Some things I've heard:

  - "why is all this stuff that users don't care about here?"
  - "can we have a lighter weight place to put technical references
 for contributors"

 So I want to consider as a community starting up our wiki. Ideas
 for what could go there:

  - Collection of links to design docs like
 https://beam.apache.org/contribute/design-documents/
  - Specialized walkthroughs like
 https://beam.apache.org/contribute/docker-images/
  - 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Robert Bradshaw]

On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles  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  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  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 
 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  wrote:
>
>> +1
>>
>> (a) we should;
>> (b) I think it will be a good place for all of the things you list;
>> (c) introductory things, like "getting started", or "programming
>> guide" that people not deeply involved in the project would expect to 
>> find
>> on beam.apache.org should stay there, not in the wiki;
>>
>> On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot <
>> echauc...@apache.org> wrote:
>>
>>> Hi Kenn,
>>> I'm +1 of course. I remember that you and I and others discussed in
>>> a similar thread about dev facing docs but it got lost at some point in
>>> time.
>>> IMHO
>>>
>>> I would add
>>> - runners specifics (e.g. how runners implement state or timer, how
>>> they split data into bundles, etc...)
>>> - probably putting online the doc I did for nexmark that summarizes
>>> the architecture and pseudo code of the queries (because some are 
>>> several
>>> thousand lines of code). I often use it to recall what a given query 
>>> does.
>>>
>>> I would remove
>>>  - BIPs / summaries of collections of JIRA
>>> because it is hard to maintain and will end up being out of date I
>>> think.
>>>
>>> Etienne
>>>
>>> Le jeudi 07 juin 2018 à 13:23 -0700, Kenneth Knowles a écrit :
>>>
>>> Hi all,
>>>
>>> I've been in half a dozen conversations recently about whether to
>>> have a wiki and what to use it for. Some things I've heard:
>>>
>>>  - "why is all this stuff that users don't care about here?"
>>>  - "can we have a lighter weight place to put technical references
>>> for contributors"
>>>
>>> So I want to consider as a community starting up our wiki. Ideas for
>>> what could go there:
>>>
>>>  - Collection of links to design docs like
>>> https://beam.apache.org/contribute/design-documents/
>>>  - Specialized walkthroughs like
>>> https://beam.apache.org/contribute/docker-images/
>>>  - Best-effort notes that just try to help out like
>>> https://beam.apache.org/contribute/intellij/
>>>  - Docs on in-progress stuff like
>>> https://beam.apache.org/documentation/runners/jstorm/
>>>  - Expanded instructions for committers, more than
>>> https://beam.apache.org/contribute/committer-guide/
>>>  - BIPs / summaries of collections of JIRA
>>>  - Docs sitting in markdown in the repo like
>>> https://github.com/apache/beam/blob/master/sdks/CONTAINERS.md and
>>> 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Kenneth Knowles]

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  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  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é 
> 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é
>> jbono...@apache.org
>> http://blog.nanthrax.net
>> Talend - http://www.talend.com
>>
>
> --
> Daniel Kulp
> dk...@apache.org - http://dankulp.com/blog
> Talend Community Coder - http://coders.talend.com
>
>

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Daniel Kulp]

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  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é  > 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é
> jbono...@apache.org 
> http://blog.nanthrax.net 
> Talend - http://www.talend.com 

-- 
Daniel Kulp
dk...@apache.org  - http://dankulp.com/blog 

Talend Community Coder - http://coders.talend.com 

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Jean-Baptiste Onofré]

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é  > 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é
> jbono...@apache.org 
> http://blog.nanthrax.net
> Talend - http://www.talend.com
> 

-- 
Jean-Baptiste Onofré
jbono...@apache.org
http://blog.nanthrax.net
Talend - http://www.talend.com

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Kenneth Knowles]

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é 
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é
> jbono...@apache.org
> http://blog.nanthrax.net
> Talend - http://www.talend.com
>

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Jean-Baptiste Onofré]

+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é
jbono...@apache.org
http://blog.nanthrax.net
Talend - http://www.talend.com

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Scott Wegner]

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

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Kenneth Knowles]

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

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Robert Bradshaw]

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

[Thomas Weise]

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

[Udi Meiri]

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


smime.p7s
Description: S/MIME Cryptographic Signature

Re: [DISCUSS] Use Confluence wiki for non-user-facing stuff

[Andrew Pilloud]

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

[Anton Kedin]

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

[Etienne Chauchot]

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

[Charles Chen]

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