Re: [eigen] Proposal: documentation for Eigen3

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

2010/6/5 Rui Maciel <rui.maciel@xxxxxxxxx>:
>
> Benoit Jacob wrote:
>> Yes, wikis are great to allow people to contribute more easily.
>> However, I think I still prefer Doxygen, for a few reasons:
>>  - it makes it much more easy, while writing documentation, to link to
>> doxygen-generated docs for classes and methods.
>
> Isn't it possible to have it both ways?   Nowadays Eigen's wiki and doxygen
> documentation coexist rather nicely.

Yes, but links in doxygen are automatic: we just write plain text and
doxygen adds the links. Can't beat that!

>
>
>>  - a wiki can disappear overnight if we do a mistake (rm
>> eigen_wiki.db) on the server.
>
> I believe there would be a fair number of users who would gladly store backups
> for Eigen's wiki.

For us to _rely on_ backups we need to know that the person isn't
going to disappear from the Eigen landscape anytime soon.

>>  - a wiki can't be read offline
>
> I believe that's possible, provided some steps are taken.  For example, the
> following mediawiki extensions appears to be very promising.
>
> http://www.mediawiki.org/wiki/Extension:Pdf_Book
> http://www.mediawiki.org/wiki/Extension:Collection
> http://www.mediawiki.org/wiki/Extension:Pdf_Export

Interesting, but none of these is exactly the same as viewing the wiki
online. I think it's a plus that the plain HTML dox are the same
regardless of whether they are local or remote.


>>  - dox files are actual files, and moreover have a very simple syntax,
>> they're almost just plain text files. Bonus for the long-term.
>>  - when one does a modification in the code, having the dox in the
>> same hg repo allows to adapt them simultaneously, keeping it in sync.
>> When we branch the code, we automatically branch the dox. With dox on
>> the wiki, it would be hard to maintain dox for Eigen 2.0, 3.0, 3.1,
>> ..., eventually 4.0.
>
> With enough users you could simply let the wiki "ferment" over time.  I
> believe there is a considerable number of users who are more than willing to
> contribute to the project and editing a wiki is a terribly easy way to do just
> that.  Moreover, it would make it possible for the documentation to cover
> corner cases which otherwise would remain undocumented.

Wait... I think there's a misunderstanding. Writing good Eigen
documentation requires a lot of technical skill, and people able to do
that are already familiar with hg (since they are using the devel
branch) and have some acquaintance with Eigen's source code, at least
some files in it, so they have seen doxygen tags and are not afraid of
them. In short, I don't think that such people need us to switch to a
wiki just to lower the barrier to entry.

I think that the biggest factor limiting the amount of documentation
we're getting right now, is the lack of documentation rigth now. It's
hard to start documenting something out of nothing. It's easier to
improve something that's been started.

Benoit