fenics team mailing list archive

[Marie Rognes <meg@xxxxxxxxx>]

I think this sounds awesome!

Some comments:

(a) A programmer's reference is also needed.

(b) About demos: It would be good to separate demos from tests.
That is, it is good to have the demos as a subset of the tests. But
I imagine that it would be easier to have well-documented demos
if there are less such. For instance, having the Mass, Poisson,
ReactionDiffusion and NeumannProblem demos in FFC adds clutter
rather than clarification (imo).

(c) "There is often a FEniCS way of doing it."
Some operations can often be surprisingly easily and compactly expressed.
(For instance, the current adaptive-poisson-demo could benefit from using
a form to assemble the error indicators instead of the current approach.)
I think we should illustrate this by maybe comparing a naive-way, better-way
and the ultimate-fenics-way for some nifty examples.
(I have not read Hans Petter's tutorial carefully, so if this is
already included, please disregard.)

--
Marie



Anders Logg wrote:
> 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.
>   
> ------------------------------------------------------------------------
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>