Subject: Re: [OMPI docs] Docs suggestions
From: manday_at_[hidden]
Date: 2013-09-24 14:42:26
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