Re: move mesos/mesos wiki pages on github into svn (was: documentation experiment: The Mesos Book)

["Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>]

Hi Adam,

My honest observation here is that this is way too much work for
documentation :)

How about just starting small, doing things incrementally, etc.?

I think it will make the onus on the existing PPMC a ton easier --
remember the goal here is
to do things in small, easily reversible steps (at least that will garner
the most 
positivity along the way I believe).

Cheers,
Chris

On 2/27/13 4:33 PM, "Adam Monsen" <ha...@gmail.com> wrote:

>On 02/27/2013 09:37 AM, Benjamin Hindman wrote:
>> IMHO having your documentation editable and living in a repository is
>> much more manageable than via an external wiki.
>
>Totally. I'm with you.
>
>> If the project wasn't mirrored at github.com/apache/mesos
>> <http://github.com/apache/mesos> then I'd suggest changing the format of
>> the documentation, but since we should just be able to point people to
>> the documentation nicely rendered in github, it seems like a
>> straightforward first step.
>
>Ah, right, the mirror! Good call.
>
>So, let's do this. Here's what I'm thinking:
>
>1. migrate all pages from http://github.com/mesos/mesos/wiki into SVN
>2. move anything wiki-like to a new wiki
>3. standardize on one markup language
>
>For #1, it would be nice to preserve history (who did what and when) for
>posterity. This is a little tricky with SVN though, see below.
>
>I suggest doing #1 and #2 in two different steps, also for posterity.
>
>For #3, Either seems fine. If you don't have a preference I'll default
>to Markdown since I've used it more.
>
>I asked Andy K. to reassign MESOS-69 to me... it seems close enough.
>
>I made some changes and went to post them to Review Board, but I ran
>into a few difficulties. First off, I didn't see a "mesos" repository,
>just a "mesos-git" repository. Is that the one I should choose?
>
>Because I want to preserve history, my "diff" is actually every commit
>performed on http://github.com/mesos/mesos/wiki (that wiki is backed by
>a standard git repository). That's 708 commits. These apply cleanly to
>trunk. The pages were in the top-level dir of the Mesos source tree, so
>I did one additional patch to move all the wiki pages into the doc/
>subdir.
>
>Here are the patches. They can be applied to trunk (git) using
>`git am *.patch`. They can be applied to trunk (svn) using
>`for i in *.patch; do patch -p1 < $i; done`.
>
>http://adammonsen.com/tmp/migrate-mesos-doc-git-patches.tgz
>(SHA-1: f0b2e9c655237f0dd9cf83daaec8f62771bad892 )
>
>If that just won't work, here's a single patch created with
>`svn diff` (after doing the for loop, above). Note that if you use
>this one you'll have to manually add the two images from the old
>github wiki.
>
>http://adammonsen.com/tmp/migrate-mesos-doc-svn.patch.gz
>(SHA-1: a5752c2b941e79d773b2e931cfcd73ac85fa7450 )
>
>I'm in the IRC channel, so if it would be easier to chat this up in
>there, stop on in. If I'm away I'll get my messages when I return.
>
>Let's talk about #2 and #3 after we finish #1.
>

Re: move mesos/mesos wiki pages on github into svn

["Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>]

Hi Adam,

On 3/4/13 11:31 AM, "Adam Monsen" <ha...@gmail.com> wrote:

>On 03/04/2013 11:15 AM, Mattmann, Chris A (388J) wrote:
>> My point is, if we have to type all of this email around making
>> documentation, then there's a problem. If the barrier to contribute
>> documentation requires 10 different tools, in different places, there
>> is a problem.
>
>I totally agree with your points, Chris!
>
>Was there something specific in what I recommended that you're providing
>constructive criticism of?

Mainly your disagreement to my point about it being way too much work based
on what was outlined for the documentation. I was simply saying KISS
principles
apply :) IOW, reading multiple paragraphs about what had to be done to
update
documentation was worrying me, that's all :)

Seems like you've got it figured out and can contribute, etc., and docs
are 
being produced, and nothing much else to see here, so I'll move right
along.

Cheers,
Chris

P.S. Instead of directly emailing the replier, and then CC'ing the dev
list, I prefer to direct
the TO: part of the message to the dev list. I assume you and Ben H. are
already subscribed to *-dev.

Re: move mesos/mesos wiki pages on github into svn

[Adam Monsen <ha...@gmail.com>]

On 03/04/2013 11:15 AM, Mattmann, Chris A (388J) wrote:
> My point is, if we have to type all of this email around making 
> documentation, then there's a problem. If the barrier to contribute
> documentation requires 10 different tools, in different places, there
> is a problem.

I totally agree with your points, Chris!

Was there something specific in what I recommended that you're providing
constructive criticism of?

My aim is/was to help consolidate the documentation as well as improve it.

Re: move mesos/mesos wiki pages on github into svn

["Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>]

Adam, TL;DR

My point is, if we have to type all of this email around making
documentation, then
there's a problem. If the barrier to contribute documentation requires 10
different tools, 
in different places, there is a problem.

This is based on my own personal experience, having been at the Foundation
since 2005.

I'll leave it at that.

Chris


On 3/4/13 10:51 AM, "Adam Monsen" <ha...@gmail.com> wrote:

>On 03/04/2013 07:45 AM, Mattmann, Chris A (388J) wrote:
>> My honest observation here is that this is way too much work for
>> documentation :)
>
>I disagree.
>
>I wrote:
>> > 1. migrate all pages from http://github.com/mesos/mesos/wiki
>> >    into SVN
>
>Already done. Bam! :)
>
>> > 2. move anything wiki-like to a new wiki
>
>This shouldn't be much worse than cutting and pasting... cutting from
>Markdown/Textile files in SVN and pasting onto the wiki. Sounds like
>there's already a confluence wiki created ( accodrding to
>http://incubator.apache.org/projects/mesos.html ).
>
>But of course, the distinction between canonical documentation vs. wiki
>documentation is subjective, so maybe everything will just stay in SVN.
>At any rate, this doesn't need to be done right away.
>
>> > 3. standardize on one markup language
>
>This is important, IMHO, and can be done automatically using pandoc.
>

Re: move mesos/mesos wiki pages on github into svn

[Adam Monsen <ha...@gmail.com>]

On 03/04/2013 07:45 AM, Mattmann, Chris A (388J) wrote:
> My honest observation here is that this is way too much work for
> documentation :)

I disagree.

I wrote:
> > 1. migrate all pages from http://github.com/mesos/mesos/wiki
> >    into SVN

Already done. Bam! :)

> > 2. move anything wiki-like to a new wiki

This shouldn't be much worse than cutting and pasting... cutting from
Markdown/Textile files in SVN and pasting onto the wiki. Sounds like
there's already a confluence wiki created ( accodrding to
http://incubator.apache.org/projects/mesos.html ).

But of course, the distinction between canonical documentation vs. wiki
documentation is subjective, so maybe everything will just stay in SVN.
At any rate, this doesn't need to be done right away.

> > 3. standardize on one markup language

This is important, IMHO, and can be done automatically using pandoc.