Subject: Re: [OMPI docs] Docs suggestions
From: manday_at_[hidden]
Date: 2013-09-24 14:50:19
To be fair, I can't judge Sphinx per-se. It might as-well be a good
system which has only been used wrongly all the time. Judging from
python documentation, there appears to be a correlation between Sphinx
and unstructured documentation, though and through that correlation it
appears likely that Sphinx encourages writing unstructured
documentation.
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