From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2007-09-20 16:44:12
On Sep 20, 2007, at 12:06 AM, Richard Friedman wrote:
> Jeff is working to create an infrastructure of a docs project
> within the open-mpi.org. We should have a formal project
> established real soon.
We have an SVN:
http[s]://svn.open-mpi.org/svn/ompi-user-docs
The [s] is only necessary for authenticated checkouts (i.e., those
who will be committing).
The Trac is almost functional -- there seems to be a problem with the
login right now (the cookies seem to be conflicting with the cookies
for the main OMPI trac; I'm probably the only person that this is a
problem for ;-) ):
https://svn.open-mpi.org/trac/ompi-user-docs
Your trac username/password are the same as your SVN username/password.
> Meantime, I'm doing some research to find out what are the right
> tools to consider for collaborative docs development. And tomorrow
> (Thurs) I'm meeting with one of our experts on DITA (Darwin
> Information Typing Architecture) at Sun. There are a number of
> free, open source, tools for authoring, building, maintaining, and
> publishing various kinds of documents collaboratively. There's
> DITA, docbook, and maybe more. (I'm pretty sure we don't want to
> use TeX)
>
> Personally, I haven't kept up with recent developments so I'm
> giving myself a crash course in all this, and it's quite a lot to
> take in. I should have something to say about tools next week.
Excellent. We had some off-list mail about this (before the mail was
setup) and you sent me some URL pointers about DITA, etc. Could you
re-send those so that others can see what you're talking about?
> The next steps might be to figure out rules of engagement, what
> needs to be done, organize teams around tasks, and set up some kind
> of milestones. The goal is to provide a complete (or, as complete
> as possible) set of user documentation for Open MPI that is
> accurate, manageable, extensible, yadda, yadda.
Hear, hear.
> Lots of questions rush immediately to mind, like:
> What should be in the user doc set?
> reference manual
> user guide
> man pages
> tutorials
> release notes
> code examples
> Where do we stand with regard to the "official" MPI documents from
> mpi-forum.org?
I'm for not including those. That information is the spec for MPI
implementations. Our man page have very stripped-down text from the
spec for each MPI function, but then add in any OMPI-specific
information as relevant. I think that's probably as far as we should
do -- let mpi-forum.org produce the spec documents (there's actually
work under way to update the in the larger MPI community -- not an
Open MPI-specific effort).
> Can we cut/paste and edit content from the 2.x reports into an Open
> MPI reference? Or do we have to worry about copyrighted content?
> Who "owns" the content currently?
> How do we keep in sync with the "official" MPI documents.
Per above, I don't think we need to worry about this.
> Is there a chance that Open MPI will become the official MPI? (Or
> am I being too naive?)
Probably not. There's still a lot of vendor / proprietary MPI's out
there that won't go away any time soon. Open MPI has reduced the
number of MPI's, but there's still a bunch.
> What are the deltas between "official" MPI 2.x and Open MPI? And
> how do we document this?
I'm not sure I understand this question...? MPI 2.x is a spec; Open
MPI is an implementation of that spec.
> As I said in an earlier email today, I'm new to this community and
> I'm not fully aware of its dynamics, how it works, who the people
> are, and what to expect. But, I'm in the door. This all started a
> few weeks ago when I told my manager that I needed to find out more
> about our (Sun's) ClusterTools, which is based on Open MPI, because
> it is an important part of Sun's HPC software stack. This led me to
> open-mpi.org, looking for the documentation. The ClusterTools
> documentation only describes how to use the ClusterTools package,
> not how to program with Open MPI. Which is appropriate.
>
> But Sun is committed to working with open source communities, and
> so my manager gave me the green light to go ahead and see if a docs
> project could be started.
>
> I'm glad to see that a number of people are out there interested in
> doing something in this area. The devil's in the details, but so's
> the fun.
>
> We may be a bit slow in getting things to the point where we're
> writing and putting back content, but we're going to get there.
> First, lets set up a working framework so things go smoothly.
Agreed.
> But here's a question we might want to discuss among ourselves over
> email in the meantime:
> I'm curious to find out how you (or programmers you know who are
> using MPI in some form or another) learn about MPI. Where do you/
> they go to develop these skills? What books/articles/courses do
> people use? Programmers are not born with innate knowledge of MPI.
> So where to they attain those skills.
Ah -- I think that there are 3 main topics here:
1. Knowledge of the MPI spec itself ("book knowledge")
2. Knowledge of how to write MPI applications ("practical knowledge")
3. Knowledge of how to use a particular MPI implementation, such as
Open MPI ("applied knowledge")
I assumed we were only talking about #3. Per your discussion above,
I'm thinking that you also want to document #1 and #2.
I think we don't want to replicate #1. www.mpi-forum.org is The
Bible and there is a larger group working on an update (MPI 2.1,
etc.). I think that those documents should stand alone by themselves.
#2 is usually covered by existing books and various tutorials on the
net. Someone cited the NCSA tutorial, which is one of my favorite to
point newbies to, as well. My $0.02 is that we can include some
basic examples of MPI programming in this project, but the real focus
should be #3: how do you use Open MPI itself.
-- Jeff Squyres Cisco Systems