fenics team mailing list archive

[Chris Richardson <chris@xxxxxxxxxxxxx>]

As a user who has come to FEniCS in the last month or so, I have some 
direct experience of
the existing documentation. I just wanted to make a few points, which do 
represent a personal point of view, but are probably also representative 
of a certain type of user.

Paper-style documentation in pdf or book form is not very useful. Whilst 
I would read something like that if studying maths or physics, HTML is 
much more useful for a computing language. Examples can be downloaded, 
and it is much more easily searchable.

The demos are great, and the best thing you've got at the moment. I find 
myself using "grep" on them to find the specific feature which I am 
interested in. I agree that they shouldn't be too heavily commented.

The doxygen generated documentation is fine, but it is a bit 
overwhelming, and it has no examples in it.

My preferred documentation model would be something like 
perldoc.perl.org or php.net which have
well-written pages on each function etc. with sections on parameters, 
return values, links to related functions, and examples. If you have 
something like this, plus the demos, that's all you need.

Another model would be to use something like "dokuwiki" which would 
allow collaboration on generating  searchable, crosslinked documentation 
with embedded examples.

Chris Richardson

P.S. I'm happy to help with the documentation effort in any way, e.g. 
proof-reading, road-testing, etc. once it
is decided.

--
Chris Richardson
BP Institute, Madingley Rd,
Cambridge CB3 0EZ, UK.
Tel: 01223 765704
Fax: 01223 765701
Web: www.bpi.cam.ac.uk <http://www.bpi.cam.ac.uk/users/chris>