+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 <k...@google.com> wrote: > OK, yea, that all makes sense to me. Like this? > > - site/documentation: writing just for users > - site/contribute: basic stuff as-is, writing for users to entice them, > links to the next... > - wiki/contributors: contributors writing just for each other > > And you also have > > - wiki/users: users writing for users > > That's interesting. > > Kenn > > > > On Mon, Jun 11, 2018 at 2:30 PM Robert Bradshaw <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 >>>>>>>>> >>>>>>>>> >>>>>
