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