fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

Dear all,

As you are all aware, FEniCS is lacking good documentation. The
situation will improve when the FEniCS book comes out, but it will
not replace a comprehensive user manual.

A very good solution to this problem has just presented itself. I
have some grant money that could go towards creating good
documentation and I have also found an ideal candidate in Kristian
Oelgaard. He should really be finishing up his thesis but has kindly
accepted to work part-time on the manual. :-)

So, let's hear some opinions on what kind of documentation users need.

Kristian, Garth, Hans Petter and I have had some initial discussions
and here are some thoughts so far. Let's get the discussion going.

1. The new documentation will consist of two parts, one called
"FEniCS User Manual" and one called "FEniCS Tutorial". The first one
will be a comprehensive manual and the second will be a tutorial based
on Hans Petter's tutorial chapter for the FEniCS book.

2. Both the user manual and tutorial will come in two different
flavors, one C++ and Python. With some clever use of LaTex \input, it
should be possible to handle with not too much extra work.

3. The user manual will replace the current user manuals for DOLFIN,
FFC, UFL and UFC. What we have now in those manuals can be used as
input.

4. The manual will focus on the user experience and therefore
concentrate on the DOLFIN interface. Specific details for FFC, UFL and
UFC will be made appendices in the new manual.

5. The manual will be available both as a PDF file and online HTML.
Hans Petter has pointed out a new tool called doconce that might be
useful for generating PDF, HTML and docstrings from a common source.
This is worth investigating as docstrings are also important and it's
extra work to maintain both docstrings and manual.

6. We need well-documented demos. It's currently unclear what the
relation is between the manual, documented demos, current demos in
DOLFIN and the examples in Hans Petter's tutorial so we need to work
out a model for this.

--
Anders

PS: The project page is here, so make sure to subscribe if you want to
follow the development of the documentation:

  https://launchpad.net/fenics-doc

There is (yet) no special mailing list for the documentation but
perhaps it will be enough to use this list.

Attachment: signature.asc
Description: Digital signature