Subject: Re: [OMPI docs] Docs suggestions
From: Shao-Ching Huang (huangsc_at_[hidden])
Date: 2013-09-24 12:53:06
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