incubator-mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Mattmann, Chris A (398J)" <>
Subject Re: [DISCUSS] Release process on wiki
Date Sat, 15 Jun 2013 02:19:59 GMT
Heya Vinod,

-----Original Message-----

From: Vinod Kone <>
Reply-To: "" <>
Date: Friday, June 14, 2013 3:12 PM
To: "" <>
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
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
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
>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
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
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
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
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
that make sense to expend resources working on.

>P.S: Open office's how to contribute to
>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
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) <
>> wrote:
>> Hi Dave,
>> -----Original Message-----
>> From: Dave Lester <>
>> Reply-To: ""
>> >
>> Date: Friday, June 14, 2013 11:26 AM
>> To: "" <>
>> Subject: Re: [DISCUSS] Release process on wiki
>> >On Thu, Jun 13, 2013 at 7:29 PM, Mattmann, Chris A (398J) <
>> >> 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
>> >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
>> >at
>> >this time, although I do think both are important to consider. Do
>> >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);
>> the
>> former requires someone with commit/PMC bit to shepherd the
>> into
>> the sources [giving them the potential for them to be quite stale as
>> 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
>> >could be frustrating.
>> Note the key word above *could*. We don't have people constantly coming
>> 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
>> fact that their community wants the model that way. Imagine the
>> of
>> documentation contribution and from all over the world with
>> internationalization
>> etc that they receive. Keeping docs in sources would be quite difficult
>> 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
>> 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?
>> 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
>> 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
>> 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
>> 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
>> the wiki?
>> What if it discourages me from contributing docs? Is that good for
>> 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
>> this issue should it arise when we have dozens of people beating our
>> 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
>> the content inside. So, you can actually search across both. B/c Google
>> a
>> horizontal search engine and not vertical, it's harder, but it can be
>> >
>> >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
>> >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:
>> WWW:
>> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>> Adjunct Assistant Professor, Computer Science Department
>> University of Southern California, Los Angeles, CA 90089 USA
>> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

View raw message