Re: [eigen] Proposal: documentation for Eigen3

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/6/6 Rui Maciel <rui.maciel@xxxxxxxxx>:
>
> Thomas Capricelli wrote:
>> Yes, i was about to say that. I use exactly this (mediawiki + pdf export)
>> to generate doc on some other projects, and i'm happy with it.
>>
>> Though, still, i'm not sure this would be the right approach for eigen. The
>> use of doxygen has proved quite successful until now, and is of far better
>> quality than the doc on the wiki.
>
> There's no need to choose between a wiki documentation and a doxygen
> reference.  Both scratch different itches and both can and do coexist rather
> nicely.
>
>
>> And i dont buy the argument about wiki database file that can be lost, this
>> is easy to backup.. I could do it, and we could setup something on
>> tuxfamily, and we could setup something on Benoit or Gael's own hard disk.
>> I'm very confident we could do something that makes Benoit happy.
>
> Indeed.  I also thought this argument was a bit far-fetched.

OK, I'm very happy to withdraw this argument if Thomas sets up wiki
backups! Personnally, I am a real n00b about all the server knowledge
that would make that easy (key-based auth, rsync...) but I guess it's
the occasion to learn...

>> Last, i agree that writing doc for eigen is technical, and it's not sure
>> that making it 'easy' (on the wiki) would help. You want people writing
>> such technical topic to be fluent in source, hg, and some such easy doc
>> tool as (say) doxygen.
>
> It's true that in order to produce documentation, the authors need to know
> what they are writing about.  Yet, if someone wishes to contribute something
> to the documentation then chances are that person already looked into the
> source code and found something which, from his experience using Eigen and
> fiddling with the source code, he believes deserves to be documented.  To put
> it in other words, we aren't talking about some clueless newbie who just
> parachuted into Eigen's world.  If someone intends to contribute to the
> documentation then naturally that person already has some experience with it.

OK, so, I agree that there is a use for documentation on both the wiki
and doxygen... which is actually what we are doing right now! Perhaps
all what was needed, was a good clarification of what should go into
doxygen, and what should go into the wiki. It's going to be impossible
to dictate absolute hard rules, but here are some thoughts:
 - The doxygen docs are automatically versioned, the wiki isn't, so
wiki pages must be careful to say to which version of Eigen they
refer.
 - Standard tutorials and API docs should go into doxygen
 - Topic-specific pages on the most important/general topics (e.g.
lazy evaluation) should go into doxygen
 - Everyone is welcome to create Wiki pages on topics that doxygen
overlooks (e.g. how to use Eigen with compiler X or interplay with
library Y or numeric type Z...). It is possible/easy to later convert
them into doxygen pages, if needed.

Cheers,
Benoit

>
>
> Rui Maciel
>
>
>
>