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