So there are at least a few people who are interested in this effort
(keep chiming in if you are interested so that we can get a tally of
who would like to be involved).
What kind of resources / organization would be useful for this
group? Indiana University graciously hosts all of Open MPI's
electronic resources (Subversion, web site, bug tracking, DNS,
mailing lists, ...) and I certainly can't speak for them, but if we
ask nicely, I'd be willing to bet that they would add some hosting
services for a documentation project (if such additional resources
would be helpful, of course).
I would also be happy to host a teleconference if talking about all
this start/admin stuff for an hour would save 1-2 weeks worth of
detailed e-mails.
-----
The only current documentation we have is:
- the web FAQ
- the README in the tarball
What is conspicuously missing is a nice PDF and/or HTML tarball with
comprehensive documentation. But I think that FAQ/README also fit
into the general category of documentation, so it might make sense to
put all 3 of these items under the control of one group. The obvious
rationale here is that all three could stay in tighter sync if
there's one group monitoring all 3.
One point worth mentioning: Open MPI is all about community
consensus, but "s/he who implements usually wins". :-) So if we get
an active group working on documentation, the FAQ could be totally re-
done if the group so decides (for example).
All this being said, the OMPI developers *have* talked about
documentation a bit over time. Here's some of the points from prior
discussions, in no particular order:
- It highly desirable to have documentation that can be output in
multiple different forms (PDF, HTML, ...whatever). If possible, the
docs should be shipped in distribution tarballs and hosted on the
OMPI web site.
- LAM/MPI had two great docs: one for installation LAM/MPI and one
for using LAM/MPI. These might be good example documents for what
Open MPI might want to do (see http://www.lam-mpi.org/using/docs/),
regardless of the back-end technology used to generate the docs.
Source LaTeX for these guides are available if it would be helpful (I
wrote most of them).
- It would be most helpful if the documentation is written in a tool
that has free editors, preferably cross-platform and available in
multiple POSIX-like environments (Solaris, Linux, OS X). MS Office
was explicitly rejected because of its requirement for Windows/OS X
(other Office clones were not really discussed). LaTeX was discussed
but wasn't favored due to the steep learning curve and general lack
of experience with it outside of academia.
- First documentation should be aimed towards users. Developer
documentation might follow.
- Once upon a time, we developers started to use doxygen for
documentation, but it has proven to be lousy for book-like entities
(IONSHO). Doxygen is decent for code documentation, but not documents.
- A few recent discussions about documentation came to the conclusion
that Docbook (www.docbook.org) looked promising, but we didn't get
deep into details / investigating the feasibility. One obvious Big
Project using Docbook is Subversion (see http://svnbook.red-
bean.com/). Docbook-produced HTML and PDF seem to look both pretty
and functional.
- It would also be nice if sub-distributions of Open MPI could take
the documentation and -- in some defined automated fashion -- be able
to do the following:
- insert their own "chapters" or "sections" that are specific to
that sub-distribution (e.g., Sun ClusterTools have some Solaris-
specific stuff, OFED have some OpenFabrics-specific stuff, etc.)
- remove/"turn off" specific sections of documentation (e.g.,
OFED would likely not include any documentation about Myricom
networks [and vice versa])
This would go a long ways towards being able to keep the community
documentation in sync with docs included in targeted/vendor OMPI
releases.
- The OMPI web site is almost entirely written in PHP and is mirrored
around the world. It would be *strongly* preferred if the web-site
hosting of the docs is fully mirror-able (because assumedly docs are
one of the things that users would want to browse the most). Hence,
requiring a new kind of server other than HTML/PHP would require
very, very strong rationale. :-)
- The technology of choice for displaying on the web site is PHP.
But that still leaves open a wide variety of choices for serving docs
via the web site, including (but not limited to):
- just posting PDFs (although having HTML-based docs would
certainly be nice)
- a PHP-based package or home-grown PHP
- generating HTML offline (via cron or whatever) and putting the
results in the web site
- ...etc.
On Sep 13, 2007, at 1:31 PM, pat.o'bry...@exxonmobil.com wrote:
Jeff,
I would also be interested. I am getting questions from my
customers
about the location of documentation.
Thanks,
Pat
Jeff Squyres
<jsquyres@cisc
o.com> To
Sent by: Open MPI Users <users@open-
mpi.org>
users-
bounces@ cc
open-mpi.org rc...@sun.com
Subject
Re: [OMPI users] OpenMPI
09/13/07 10:33 Documentation?
AM
Please respond
to
Open MPI Users
<users@open-mp
i.org>
I would be very happy to help setup a documentation community --
goodness knows we need more/better documentation for Open MPI!
Who else would be interested?
On Sep 13, 2007, at 5:13 AM, Amit Kumar Saha wrote:
Hi Richard,
On 9/12/07, Richard Friedman <rc...@sun.com> wrote:
Amit:
Well, as far as I know a documentation community within OpenMPI
has not yet
been formed, but maybe it is time to send out a general call to
the OpenMPI
members to see about creating one.
I'm new to the OpenMPI community myself, so I'm not yet sure how
this can
be done. But we can find out.
Thanks for the interest.
Well, some has to take the initiative, and it would be ideal to have
an experienced Open MPI programmer take the lead role and members
like
me can be contributors.
Regards,
Amit
--
Amit Kumar Saha
[URL]:http://amitsaha.in.googlepages.com
_______________________________________________
users mailing list
us...@open-mpi.org
http://www.open-mpi.org/mailman/listinfo.cgi/users
--
Jeff Squyres
Cisco Systems
_______________________________________________
users mailing list
us...@open-mpi.org
http://www.open-mpi.org/mailman/listinfo.cgi/users
_______________________________________________
users mailing list
us...@open-mpi.org
http://www.open-mpi.org/mailman/listinfo.cgi/users
--
Jeff Squyres
Cisco Systems
