You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mesos.apache.org by Adam Monsen <ha...@gmail.com> on 2013/02/26 02:03:22 UTC
documentation experiment: The Mesos Book
I've heard several folks mention the need to improve documentation for
Mesos. I kicked off a little experimental book. There's almost zero
content so far (and what exists is cut-and-pasted from existing public
docs), I'm just looking for feedback on my approach. Check it out!
https://github.com/meonkeys/the-mesos-book
Thoughts?
The idea would be to port all existing stable documentation into this
book. It would become the most complete and best reference for Mesos
users (perhaps developers, too). Other documentation sources would still
exist such as in-the-code API docs and fluid/collaborative docs (wiki
pages).
I went with Pandoc Markdown because I read and enjoyed The Little
MongoDB Book by Karl Seguin
(http://openmymind.net/2011/3/28/The-Little-MongoDB-Book/ ,
https://github.com/karlseguin/the-little-mongodb-book ). I've also read
quite a bit of Scott Chacon's awesome book Pro Git ( http://progit.org ,
https://github.com/progit/progit ), which is similarly written in
Markdown and processed into other beautiful formats using software tools.
Re: move mesos/mesos wiki pages on github into svn
Posted by "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
Posted by 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
Posted by "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
Posted by 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.
Re: move mesos/mesos wiki pages on github into svn (was:
documentation experiment: The Mesos Book)
Posted by "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.
>
move mesos/mesos wiki pages on github into svn (was: documentation
experiment: The Mesos Book)
Posted by Adam Monsen <ha...@gmail.com>.
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: documentation experiment: The Mesos Book
Posted by Benjamin Hindman <be...@eecs.berkeley.edu>.
IMHO having your documentation editable and living in a repository is much
more manageable than via an external wiki. It enables someone to both make
changes to some code/interface AND make changes to the documentation in the
same commit! By encouraging this as well we can keep our documentation much
more up to date than if it were to live in a separate place. The other nice
property of storing documentation in the repository is that we can "freeze"
it with releases so that people can get accurate documentation for whatever
version they are working with (without lots of noise in the documentation).
If the project wasn't mirrored at 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.
On Tue, Feb 26, 2013 at 4:40 PM, Adam Monsen <ha...@gmail.com> wrote:
> Hi Ben,
>
> Thanks for your reply.
>
> On 02/26/2013 02:18 PM, Benjamin Hindman wrote:
> > a great first step would be to get the old documentation that
> > still lives at https://github.com/mesos/mesos/wiki into the
> > repository (you can submit reviews for that).
>
> So you're saying content at https://github.com/mesos/mesos/wiki should
> be committed to source control?
>
> Or should I just do https://issues.apache.org/jira/browse/MESOS-69 first
> and migrate https://github.com/mesos/mesos/wiki to an Apache wiki?
>
>
Re: documentation experiment: The Mesos Book
Posted by Adam Monsen <ha...@gmail.com>.
On 03/03/2013 09:51 PM, Mattmann, Chris A (388J) wrote:
> 1. The canonical bits for documentation for Apache Mesos (incubating) need
> to live on Apache hardware.
Yep, agreed.
> 2. To help with #1, you file JIRA issues, and submit documentation
> patches, and then one of the PPMC
> and/or committers on the project will work with you to get them into the
> sources, with you earning merit
> along the way. Apache is a meritocracy and so long as you are operating in
> a friendly, meritocratic way, the PPMC may recognize you for your work and
> invite you to be part of the PPMC on the project.
Yep, sounds good!
Chris, we've already moved all docs from github into the ASF-hosted
Mesos SVN repository.
Did you see these two mailing list messages?
* comment on MESOS-69, (which can probably be closed):
http://mail-archives.apache.org/mod_mbox/incubator-mesos-dev/201303.mbox/%3CJIRA.12530808.1320805617429.373037.1362352632489%40arcas%3E
* "ship it" on review 9664:
http://mail-archives.apache.org/mod_mbox/incubator-mesos-dev/201303.mbox/%3C20130303194011.27098.94622%40reviews.apache.org%3E
Re: documentation experiment: The Mesos Book
Posted by "Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>.
Hi Adam,
I think what Ben is saying is that:
1. The canonical bits for documentation for Apache Mesos (incubating) need
to live on Apache hardware.
Looking at Mesos's Incubating page we've got a wiki and a web page:
http://incubator.apache.org/projects/mesos.html
Those would be the best candidates to start from.
2. To help with #1, you file JIRA issues, and submit documentation
patches, and then one of the PPMC
and/or committers on the project will work with you to get them into the
sources, with you earning merit
along the way. Apache is a meritocracy and so long as you are operating in
a friendly, meritocratic way, the PPMC may recognize you for your work and
invite you to be part of the PPMC on the project.
HTH.
Cheers,
Chris
On 2/26/13 4:40 PM, "Adam Monsen" <ha...@gmail.com> wrote:
>Hi Ben,
>
>Thanks for your reply.
>
>On 02/26/2013 02:18 PM, Benjamin Hindman wrote:
>> a great first step would be to get the old documentation that
>> still lives at https://github.com/mesos/mesos/wiki into the
>> repository (you can submit reviews for that).
>
>So you're saying content at https://github.com/mesos/mesos/wiki should
>be committed to source control?
>
>Or should I just do https://issues.apache.org/jira/browse/MESOS-69 first
>and migrate https://github.com/mesos/mesos/wiki to an Apache wiki?
>
Re: documentation experiment: The Mesos Book
Posted by Adam Monsen <ha...@gmail.com>.
Hi Ben,
Thanks for your reply.
On 02/26/2013 02:18 PM, Benjamin Hindman wrote:
> a great first step would be to get the old documentation that
> still lives at https://github.com/mesos/mesos/wiki into the
> repository (you can submit reviews for that).
So you're saying content at https://github.com/mesos/mesos/wiki should
be committed to source control?
Or should I just do https://issues.apache.org/jira/browse/MESOS-69 first
and migrate https://github.com/mesos/mesos/wiki to an Apache wiki?
Re: documentation experiment: The Mesos Book
Posted by "Mattmann, Chris A (388J)" <ch...@jpl.nasa.gov>.
Ben, great job pointing this out to Adam.
Cheers,
Chris
On 2/26/13 2:18 PM, "Benjamin Hindman" <be...@eecs.berkeley.edu> wrote:
>Hey Adam!
>
>I love the enthusiasm on improving Mesos documentation! That being said,
>it's probably a bit too early for a book. ;)
>
>I think it would be great to create a documentation ticket on JIRA so we
>can figure out exactly what documentation we want to start creating. IMHO,
>a great first step would be to get the old documentation that still lives
>at https://github.com/mesos/mesos/wiki into the repository (you can submit
>reviews for that). After that we can start editing the documentation
>together to get it up to date. I'm not opposed to continuing to use Github
>markdown for this (for now), since we can still point people to
>github.com/apache/mesos/documenation or something similar in order to
>"render" the documentation correctly. That being said, I'd prefer that all
>of our actual work is done within the Apache infrastructure (JIRA, Review
>Board, etc) to keep things consistent. Seems like we could always port the
>documentation over to something else in the future if Apache provides
>other
>wiki options (note: I know that Confluence wiki exists, but I'm not sure
>if
>we'd want to go down that route).
>
>I look forward to any patches that come our way!
>
>Ben.
>
>
>On Mon, Feb 25, 2013 at 5:03 PM, Adam Monsen <ha...@gmail.com> wrote:
>
>> I've heard several folks mention the need to improve documentation for
>> Mesos. I kicked off a little experimental book. There's almost zero
>> content so far (and what exists is cut-and-pasted from existing public
>> docs), I'm just looking for feedback on my approach. Check it out!
>>
>> https://github.com/meonkeys/the-mesos-book
>>
>> Thoughts?
>>
>> The idea would be to port all existing stable documentation into this
>> book. It would become the most complete and best reference for Mesos
>> users (perhaps developers, too). Other documentation sources would still
>> exist such as in-the-code API docs and fluid/collaborative docs (wiki
>> pages).
>>
>> I went with Pandoc Markdown because I read and enjoyed The Little
>> MongoDB Book by Karl Seguin
>> (http://openmymind.net/2011/3/28/The-Little-MongoDB-Book/ ,
>> https://github.com/karlseguin/the-little-mongodb-book ). I've also read
>> quite a bit of Scott Chacon's awesome book Pro Git ( http://progit.org ,
>> https://github.com/progit/progit ), which is similarly written in
>> Markdown and processed into other beautiful formats using software
>>tools.
>>
>>
Re: documentation experiment: The Mesos Book
Posted by Benjamin Hindman <be...@eecs.berkeley.edu>.
Hey Adam!
I love the enthusiasm on improving Mesos documentation! That being said,
it's probably a bit too early for a book. ;)
I think it would be great to create a documentation ticket on JIRA so we
can figure out exactly what documentation we want to start creating. IMHO,
a great first step would be to get the old documentation that still lives
at https://github.com/mesos/mesos/wiki into the repository (you can submit
reviews for that). After that we can start editing the documentation
together to get it up to date. I'm not opposed to continuing to use Github
markdown for this (for now), since we can still point people to
github.com/apache/mesos/documenation or something similar in order to
"render" the documentation correctly. That being said, I'd prefer that all
of our actual work is done within the Apache infrastructure (JIRA, Review
Board, etc) to keep things consistent. Seems like we could always port the
documentation over to something else in the future if Apache provides other
wiki options (note: I know that Confluence wiki exists, but I'm not sure if
we'd want to go down that route).
I look forward to any patches that come our way!
Ben.
On Mon, Feb 25, 2013 at 5:03 PM, Adam Monsen <ha...@gmail.com> wrote:
> I've heard several folks mention the need to improve documentation for
> Mesos. I kicked off a little experimental book. There's almost zero
> content so far (and what exists is cut-and-pasted from existing public
> docs), I'm just looking for feedback on my approach. Check it out!
>
> https://github.com/meonkeys/the-mesos-book
>
> Thoughts?
>
> The idea would be to port all existing stable documentation into this
> book. It would become the most complete and best reference for Mesos
> users (perhaps developers, too). Other documentation sources would still
> exist such as in-the-code API docs and fluid/collaborative docs (wiki
> pages).
>
> I went with Pandoc Markdown because I read and enjoyed The Little
> MongoDB Book by Karl Seguin
> (http://openmymind.net/2011/3/28/The-Little-MongoDB-Book/ ,
> https://github.com/karlseguin/the-little-mongodb-book ). I've also read
> quite a bit of Scott Chacon's awesome book Pro Git ( http://progit.org ,
> https://github.com/progit/progit ), which is similarly written in
> Markdown and processed into other beautiful formats using software tools.
>
>