mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vinod Kone <vinodk...@gmail.com>
Subject Re: [DISCUSS] Release process on wiki
Date Fri, 14 Jun 2013 22:12:48 GMT
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?

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?

3) How easy is it to associate documentation to releases in Wiki? Its
straightforward when we work in the repo.

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?

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


On Fri, Jun 14, 2013 at 2:39 PM, Mattmann, Chris A (398J) <
chris.a.mattmann@jpl.nasa.gov> wrote:

> Hi Dave,
>
> -----Original Message-----
>
> From: Dave Lester <davelester@berkeley.edu>
> Reply-To: "mesos-dev@incubator.apache.org" <mesos-dev@incubator.apache.org
> >
> Date: Friday, June 14, 2013 11:26 AM
> To: "mesos-dev@incubator.apache.org" <mesos-dev@incubator.apache.org>
> Subject: Re: [DISCUSS] Release process on wiki
>
> >On Thu, Jun 13, 2013 at 7:29 PM, Mattmann, Chris A (398J) <
> >chris.a.mattmann@jpl.nasa.gov> 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: chris.a.mattmann@nasa.gov
> WWW:  http://sunset.usc.edu/~mattmann/
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> Adjunct Assistant Professor, Computer Science Department
> University of Southern California, Los Angeles, CA 90089 USA
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>
>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message