Subject: Re: [OMPI docs] Docs suggestions
From: Kelly Black (kjblack_at_[hidden])
Date: 2013-09-24 17:47:46
Hello,
If you want output in HTML then just using HTML is a good choice. It would
be relatively straightforward to use a template system to make it easier to
maintain and ensure uniformity over multiple pages with options for
different page lengths. Working in HTML is relatively straight forward and
there are multiple choices with respect to authoring tools to appeal to
more people.
It is a good idea to make the Open MPI aspects the primary material for
the document. I think it is important to have the simple examples and broad
overview of MPI programming. I recently came back to MPI after a long
hiatus, and I found it difficult to find good material to get started. I
ended up having to collect material from a wide variety of sources which
was frustrating.
-Kel
_______________________________________________________
Kelly Black Phone: (315) 600-8334
Clarkson University Fax: (315) 268-2371
Department of Math. & C.S.
PO Box 5815
Potsdam, NY 13699-5815
USA
On Tue, Sep 24, 2013 at 2:42 PM, <manday_at_[hidden]> wrote:
> Sphinx is one of the most awful and dysfunctional documentation systems
> that I've ever seen. Admitted, I only had to deal with it in the context
> of Python and associates, but that was enough to seriously traumatize
> me.
>
> Considering documentation, your primary concern should be that of
> finding a powerful and yet easy-to-write markup language. Presentation
> is a subordinate matter - tools like pandoc will eventually always allow
> you to render any kind of presentation you prefer.
>
> In my opinion, HTML and EPUB are the best things we have for writing
> technical documents at the moment. EPUB still suffers from not being
> able to display mathematical contents, but that should be of little
> meaning for OpenMPI. HTML5 on the other hand, is a bit lacking with
> regard to defining meta data.
>
> Writing HTML isn't that bad. It may be not as convenient as writing TeX,
> but it offers the considerable advantage of being a clearly structured
> and readily available markup language.
>
> I've had only good experiences writing documents in HTML5, so if I were
> to give a vote, I'd opt for HTML.
>
> On Tue, Sep 24, 2013 at 09:53:06AM -0700, Shao-Ching Huang wrote:
> > Hi,
> >
> > Regarding the source format, if LaTeX is out of the table, may I
> > suggest Sphinx, http://sphinx-doc.org/. Sphinx can generate outputs in
> > HTML, latex, texinfo, pdf, etc. formats. The source is mostly
> > reStructuredText, so like asciidoc and markdown, it is less burden for
> > writers. Embedded code examples can be highlighted by pygment
> > (http://pygments.org/).
> >
> > Shao-Ching Huang
> >
> >
> > On Tue, Sep 24, 2013 at 9:07 AM, Jeff Squyres (jsquyres)
> > <jsquyres_at_[hidden]> wrote:
> > > On the weekly Open MPI engineering call today, we talked about the
> docs project.
> > >
> > > The developer community had a few suggestions:
> > >
> > > 1. Affirmation of focusing on user-level documentation of Open
> MPI-specific issues. E.g., here's how OMPI's wrapper compilers work;
> here's how to use --showme, here's how to use OMPI's mpirun, here's how to
> set OMPI MCA params, ...etc. A short MPI programming tutorial would be ok,
> but keep it short/high level, and use it as a gateway to explaining the
> OMPI tools surrounding an MPI source code (because there's books and lots
> of google material on writing MPI code).
> > >
> > > 2. Additionally, try to make docs that can be fairly stable over time:
> stuff that won't need to be updated frequently, because documentation tends
> to suffer from bit rot. So if we can intentionally write fairly stable
> docs to start with, they'll have a longer shelf life.
> > >
> > > Meaning: don't document every OMPI detail. Rather, (at least to start
> with) document all the high-level OMPI concepts that haven't changed in a
> long time: ./configure && make -j 32 install, wrapper compilers, mpirun,
> MCA params, etc.
> > >
> > > 3. The community suggested that PDF might not be a good primary format
> (this surprised me). For example, Google scores PDFs lower than HTML --
> that's a good point; I didn't know that.
> > >
> > > Put differently: apparently, kids these days want to read web pages,
> not PDFs. So the question naturally of source code format was raised --
> the old "latex can render into both PDF and HTML" issue came up. I don't
> know if anyone has tried it recently, but the HTML emitted by latex2html is
> actually pretty awful/horrible/ugly. Some suggestions were floated that
> might be good instead of latex (because they can render
> > >
> > > - Asciidoc, which renders to both HTML and PDF (and others),
> http://www.methods.co.nz/asciidoc/
> > >
> > > - Pandoc, which will let you convert arbitrarily between different
> markup/markdown formats: http://johnmacfarlane.net/pandoc/
> > >
> > > - Markdown, a markup language:
> http://daringfireball.net/projects/markdown/ (probably need to route
> through Pandoc to get PDF from Markdown)
> > >
> > > - Docbook, but that's basically writing XML, which feels kinda
> ugly/blech.
> > >
> > > Thoughts?
> > >
> > > --
> > > Jeff Squyres
> > > jsquyres_at_[hidden]
> > > For corporate legal information go to:
> http://www.cisco.com/web/about/doing_business/legal/cri/
> > >
> > > _______________________________________________
> > > docs mailing list
> > > docs_at_[hidden]
> > > http://www.open-mpi.org/mailman/listinfo.cgi/docs
> > _______________________________________________
> > docs mailing list
> > docs_at_[hidden]
> > http://www.open-mpi.org/mailman/listinfo.cgi/docs
> _______________________________________________
> docs mailing list
> docs_at_[hidden]
> http://www.open-mpi.org/mailman/listinfo.cgi/docs
>