From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2007-09-18 06:55:11
On Sep 18, 2007, at 5:38 AM, jody wrote:
> I was just wondering how we'll start this documentation.
BTW, before we get started, I want to make one thing very, very
clear: it's "Open MPI". Two words. Not one word smushed together.
A lot of people get it wrong, but it's a brand, and in the official
OMPI documentation, we must get this right. :-)
-------------
I think we need a few procedural / logistics worked out first; some
are simple, some require a little more thought. I was kinda hoping
that Richard Friedman would take the lead here. :-)
Here's some thoughts on things that we'll need to decide before we
get rolling:
1. SVN repository name. "ompi-docs" is already used, so we'll need
to pick another.
2. Which technology to use for the documentation. I think Richard
has lots of experience here, so I'll let him expound on it.
3. How to allow people to join/contribute -- there's some legal/
intellectual property issues here that I'll look into (IANAL, but my
understanding is that contributing docs is different than
contributing code).
4. What process(es) and standards will be used to create and verify
the documentation.
5. What process(es) will be used to maintain the docs over time
(e.g., ensure that they are up-to-date in time for a release, etc.).
There will need to be some integration with the Open MPI developer
community -- I'm here to help facilitate that.
6. What document(s), exactly, are we going to produce.
> I think to begin with, we need something like a table of contents.
>
> I guess some areas we should cover are
> - general introduction to the MPI model
> - about MPI implementations
> - about the structure of OpenMPI - brief explanation of orte, mca,
> opal etc
> - installing OpenMPI (much can be taken from the FAQ)
> This should include good descriptions of all parameters for the
> configure command
> as well as sections for systems with particular ways for
> installation
> - compiling OpenMPI (much can be taken from the FAQ)
> - running OpenMPI (much can be taken from the FAQ)
> - tuning OpenMPI performance
FWIW, there might be value in having more than one document:
- compiling / installing Open MPI: a document for sysadmins / cluster
installers
- using Open MPI: a document for end-users
We did this for LAM/MPI and it was quite handy. I'm not necessarily
tied to this idea -- I just toss it out to the group to see what
people think.
> Perhaps something like a tutorial would be useful:
> Designing, implementing and running a simple but nnon-trivial
> MPI-application, introducing some of the basic MPI commands.
This could be useful, but let's limit the MPI aspect of it (there are
other MPI tutorials available on the net -- let's not try to
duplicate those); let's have it focus more on the Open MPI-specific
aspects. Perhaps we can show the canonical "hello world" and/or
"ring" applications in all 4 supported languages.
> Any other ideas?
> Should we also include a MPI-reference or should we simply
> refer to the man-pages or the books?
At least to start, I think we should refer to the man pages and other
resources.
My $0.02...
-- Jeff Squyres Cisco Systems