Btw Chris, do you have the ability to grant me edit access for the mesos wiki page? I would like to use it to capture some stuff (e.g., new feature design)? If you don't I can create an INFRA ticket?
On Fri, Jun 14, 2013 at 7:19 PM, Mattmann, Chris A (398J) < [email protected]> wrote: > Heya Vinod, > > -----Original Message----- > > From: Vinod Kone <[email protected]> > Reply-To: "[email protected]" <[email protected] > > > Date: Friday, June 14, 2013 3:12 PM > To: "[email protected]" <[email protected]> > Subject: Re: [DISCUSS] Release process on wiki > > >Thanks Chris for your POV. I think we all agree that Wiki is more user > >friendly than git. But my (and likely others) concerns are > > > >1) If docs are editable on both wiki and git, then which one is the > >authoritative source? If one of them goes stale, which one should the > >user/contributor refer to? > > Great question -- why does one have to be the authoritative source over > the other? It's quite possible that they won't have overlapping content. > And if they do, it really only costs us an email to a (potentially > confused) > user pointing them at the right source. This requires us to be active on > the dev lists and responsive and looking to help -- Mesos right now > definitely > fits that bill. I'm sure you or Ben H or Ben M or Andy or anyone else > (even me!) :) > may be able to point peeps in the right direction on that. > > > > >2) How to keep the docs in sync? If some one edits the docs in the wiki, > >how do we get it into our git repo? This involves PMC/Committer to > >shepherd > >no? Then why not involve pmc/committer early and circumvent the wiki edit? > > Who sez they have to be in sync? Like I said they could be overlapping > content, > or not. If they are overlapping then one can grow stale but I would > estimate the > cost function for that to be minimal. And it may be driven by our own > interest > to fix this or we may have some superstar user that fixes it for us that we > then nominate for PMC and then sign them up for this fantastic task (heh). > > > > >3) How easy is it to associate documentation to releases in Wiki? Its > >straightforward when we work in the repo. > > +1 release docs shipping with releases makes perfect sense to me. No reason > though that there can't be complementary (even overlapping) docs on the > wiki. > No biggie. > > > > >Maybe, one way we could let users use wiki to contribute is, if there is > >tooling available that can generate a ReviewBoard patch when someone edits > >a wiki, ala github pull request to RB patch? > > Haha, yikes that sounds like work for you guys (PMC) that you don't need > to do. > Let users and contributors edit the wiki to the hearts content and improve > Apache > Mesos doc. The policies/procedures for what's canonical/etc. in those docs > can be > less formal and more based on social norms; users' actual comments; and > improvements > that make sense to expend resources working on. > > > > >P.S: Open office's how to contribute to > >wiki< > http://wiki.openoffice.org/wiki/Documentation/Dashboard/Wiki_Editing_ > >Policy> > >looks > >pretty ominous to me :) > > Hehe, same to me! /me ducks from the Apache Ooo PMC members sneaking > around on this list lol > > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > Chris Mattmann, Ph.D. > Senior Computer Scientist > NASA Jet Propulsion Laboratory Pasadena, CA 91109 USA > Office: 171-266B, Mailstop: 171-246 > Email: [email protected] > WWW: http://sunset.usc.edu/~mattmann/ > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > Adjunct Assistant Professor, Computer Science Department > University of Southern California, Los Angeles, CA 90089 USA > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > > > > > > > >On Fri, Jun 14, 2013 at 2:39 PM, Mattmann, Chris A (398J) < > >[email protected]> wrote: > > > >> Hi Dave, > >> > >> -----Original Message----- > >> > >> From: Dave Lester <[email protected]> > >> Reply-To: "[email protected]" > >><[email protected] > >> > > >> Date: Friday, June 14, 2013 11:26 AM > >> To: "[email protected]" <[email protected]> > >> Subject: Re: [DISCUSS] Release process on wiki > >> > >> >On Thu, Jun 13, 2013 at 7:29 PM, Mattmann, Chris A (398J) < > >> >[email protected]> wrote: > >> > > >> >> I would just do both. Let contributions and time > >> >> decide; rather than just picking one. > >> > > >> > > >> >I disagree. In this case I see two distinct concerns related to > >> >documentation and the wiki: 1) making it clear and simple for how to > >> >contribute to the project documentation, and 2) making it easy to use > >>the > >> >documentation and get started with Mesos. > >> > >> And: > >> > >> 3) Enabling contribution to documentation (which is different from #1 > >> [making > >> it clear] and from #2 [using the documentation]) > >> > >> > > >> >I personally think the latter concern much more pressing for user > >>growth > >> >at > >> >this time, although I do think both are important to consider. Do > >>others > >> >think the former is more important? > >> > >> I'm of the mindset having been around the foundation since 2005-, and a > >> number > >> of projects that each (shipping docs with release; and keeping docs in > >> wiki) has > >> their benefits and use cases. The latter allows documentation to evolve > >> much more > >> rapidly and also visually (e.g., through editors like Confluence); > >>whereas > >> the > >> former requires someone with commit/PMC bit to shepherd the > >>documentation > >> into > >> the sources [giving them the potential for them to be quite stale as > >>those > >> sources > >> become stale]. > >> > >> However the above is a straw man.I see advantages to both and have lived > >> them > >> through in a number of high and low profile open source projects. > >> > >> > > >> > As a developer who is getting starting with Mesos, having multiple > >> >sources > >> >of truth for the project (documentation stored in git, and also the > >>wiki) > >> >could be frustrating. > >> > >> Note the key word above *could*. We don't have people constantly coming > >>to > >> the mailing lists complaining about this delineation. And if they did, I > >> would > >> suggest to them the same (and it really depends on what their role is in > >> the > >> project -- are they PMC/committer yet? are they simply a user?, etc.) > >> > >> Take for example Apache Open Office -- a very formal PMC organization > >> rightly so > >> due to the diversity of types and kinds of contributions -- and due to > >>the > >> fact that their community wants the model that way. Imagine the > >>rate/types > >> of > >> documentation contribution and from all over the world with > >> internationalization > >> etc that they receive. Keeping docs in sources would be quite difficult > >>if > >> updating those docs required the contributors to be PMC or committer - > >> especially > >> in the case that they receive non technical documentation and > >> contributions from > >> people that will never touch SVN or Git, like ever. But they write > >> documentation in > >> e.g., some editor or wiki, and then contribute it separate of the > >>release > >> cycle of > >> the system. > >> > >> On the opposite extreme end, in a project with very small sources; high > >> rate of > >> commit; tons of inclusivity; I can see saying look we want docs only in > >> sources, > >> we don't need a wiki being a decent choice. Until the first user that > >> cares nothing > >> about the sources, but only the binary, and that writes a great tutorial > >> on the > >> software and wants to share it comes along. Then what's the use case? > >>That > >> tutorial > >> has to be shepherded or brought into the sources by a committer or PMC > >> member, creating > >> more work. When instead, that user could have gone to a wiki, turned the > >> editor on, > >> dumped their doc into it, clicked save, and been done. It's in our > >> advantage to have > >> the docs here on ASF hardware and the bits here, in whatever form they > >> manifest (wiki; > >> *.md files in Git, etc.) > >> > >> Mesos isn't on either end of these opposites, and is more in-between > >>like > >> most > >> projects are. For that reason along with numerous others I've suggested, > >> it probably > >> makes sense to support both. > >> > >> Beyond this, it's also not a question of "shutting down" documentation > >>on > >> the wiki. > >> That's not something really that should be dictated, nor is it very > >> community friendly. > >> I'm involved with the project, if for nothing else than teaching the > >> Apache way, vote'ing > >> on releases and mentoring. I enjoy the wiki, a lot more than I do > >>checking > >> out a source > >> tree, running a few git commands and then update/pushing it and waiting > >> for it to appear > >> on some site. For that reason that there is at least 1 person on the > >> project that likes > >> a wiki, I'd ask, VOTE'ing to declare one versus the other defunct or not > >> isn't very > >> friendly to me or anyone else that likes the wiki. I'd ask: what happens > >> if everyone > >> +1s the Git docs, and -1s me? What should I do then? Stop putting stuff > >>on > >> the wiki? > >> What if it discourages me from contributing docs? Is that good for > >>Mesos? > >> Or the community? > >> > >> >There's no search between the docs and wiki, and I'm > >> >not clear if there is a distinction between where I would go to answer > >> >specific questions. When contributing documentation, I'm also not sure > >> >which source I would contribute to. > >> > >> Hypothetical, let's support this with real use cases and data and > >>address > >> this issue should it arise when we have dozens of people beating our > >>door > >> down for searching across the wiki and docs -- furthermore, I'd actually > >> suggest that in fact you can search across both, with Google. Google > >> indexes > >> Apache's Confluence deployment; as do they index our Git and SVN repos > >>and > >> the content inside. So, you can actually search across both. B/c Google > >>is > >> a > >> horizontal search engine and not vertical, it's harder, but it can be > >>done. > >> > >> > > >> >I'm in favor of using just one source. If making it easy to use the > >> >documentation is the priority then I think rendering markdown files is > >>a > >> >fine approach for now. > >> > >> My honest suggestion: put your time and effort into improving what you'd > >> like > >> (the source docs), and let me and anyone else that wants to put stuff on > >> the > >> wiki do our thing too. Then, beyond that, let's add a link on both: (1) > >> from > >> the wiki to git: Apache src docs; and from src docs to the wiki. Done. > >> > >> Cheers, > >> Chris > >> > >> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > >> Chris Mattmann, Ph.D. > >> Senior Computer Scientist > >> NASA Jet Propulsion Laboratory Pasadena, CA 91109 USA > >> Office: 171-266B, Mailstop: 171-246 > >> Email: [email protected] > >> WWW: http://sunset.usc.edu/~mattmann/ > >> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > >> Adjunct Assistant Professor, Computer Science Department > >> University of Southern California, Los Angeles, CA 90089 USA > >> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ > >> > >> > >> > >> > >
