[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


(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@xxxxxxxxxx> 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.

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.


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?