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 <rober...@google.com> wrote:
> > On Fri, Jun 8, 2018 at 2:18 PM Kenneth Knowles <k...@google.com> wrote:
> >
> > > I disagree strongly here - I don't think the wiki will have appropriate
> > > polish for users. Even if carefully
> > > polished I don't think the presentation style is right, and it is not
> > > flexible. Power users will find it, of
> > > course.
> >
> > I wasn't imagining a wiki as a platform for developers to author
> > documentation, rather a place for users to author
> > content for other users (tips and tricks, handy PTransforms, etc.) at a
> > much lower bar than expecting users to go in
> > and update our documentation. I agree with the goal of not (further)
> > fragmenting our documentation.
> > As for mixing contributor vs. user information on the same site, I think
> > it's valuable to have some integration and
> > treat the two as a continuum (after all, our (direct) users are already
> > developers) and consider it an asset to have
> > a "contribute" heading right in the main site. (Perhaps, if it's confusing,
> > we could move it all the way to the
> > right.) I don't think we'll be doing ourselves a favor by blinding copying
> > all the existing docs to a wiki. That
> > being said I think it makes sense to start playing with using a wiki, and
> > see how much value that adds on top of
> > what we already have.
> > >
> > > > On Fri, Jun 8, 2018 at 12:05 PM Thomas Weise <t...@apache.org> wrote:
> > > > > +1 most of the contributor material could live on Wiki and there it
> > > > > will be easier to maintain (perhaps the
> > > > > lower bar for updates will lead to more information and increased
> > > > > maintenance). Contribution policy related
> > > > > material should remain on the website and go through proper
> > > > > review/versioning.
> > > > >
> > > > > On Fri, Jun 8, 2018 at 11:44 AM, Udi Meiri <eh...@google.com> wrote:
> > > > > > (a) Yes.(b) I'm interested in putting documentation for
> > > > > > contributors there. (test triage guide, precommit
> > > > > > and postcommit guidelines, processes, etc.)It'd be faster than
> > > > > > having to go through the motions of a github
> > > > > > pull request and a review process.(c) Anything that goes to a wide
> > > > > > audience, such as SDK users. That would
> > > > > > need review.
> > > > > > Also, have you looked at https://wiki.apache.org/general/ ? (not
> > > > > > sure if that's Confluence)
> > > > > >
> > > > > > On Fri, Jun 8, 2018 at 10:07 AM Andrew Pilloud
> > > > > > <apill...@google.com> wrote:
> > > > > > > +1 It would be really nice to have a lightweight place to share
> > > > > > > that is more searchable then random Google
> > > > > > > docs.
> > > > > > > Andrew
> > > > > > > On Fri, Jun 8, 2018 at 9:35 AM Anton Kedin <ke...@google.com>
> > > > > > > wrote:
> > > > > > > > +1
> > > > > > > >
> > > > > > > > (a) we should;
> > > > > > > > (b) I think it will be a good place for all of the things you
> > > > > > > > list;
> > > > > > > > (c) introductory things, like "getting started", or
> > > > > > > > "programming guide" that people not deeply involved
> > > > > > > > in the project would expect to find on beam.apache.org should
> > > > > > > > stay there, not in the wiki;
> > > > > > > > On Fri, Jun 8, 2018 at 12:56 AM Etienne Chauchot
> > > > > > > > <echauc...@apache.org> wrote:
> > > > > > > > > Hi Kenn,I'm +1 of course. I remember that you and I and
> > > > > > > > > others discussed in a similar thread about dev
> > > > > > > > > facing docs but it got lost at some point in time.IMHO
> > > > > > > > > I would add - runners specifics (e.g. how runners implement
> > > > > > > > > state or timer, how they split data into
> > > > > > > > > bundles, etc...)- probably putting online the doc I did for
> > > > > > > > > nexmark that summarizes the architecture
> > > > > > > > > and pseudo code of the queries (because some are several
> > > > > > > > > thousand lines of code). I often use it to
> > > > > > > > > recall what a given query does.
> > > > > > > > > I would remove - BIPs / summaries of collections of
> > > > > > > > > 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
