[ensembl-dev] Upgrade the mail-list

[Thomas Juettemann]

Adding my 2 cent:
I see myself as an intermediate Perl programmer and recently started
using the  API. I second Kieron that using Doxygen made my start much
easier. Autocompletion and being able to search for methods across all
Modules saved me an immense amount of time. I took the API training
course and had a 45 year old biologist who just started
Perl/Unix/Bioinformatics, and he was able navigation through the
system within 20 min. Really impressed me.

However, when coding I often prefer to look at the good ol' Perldoc.
But it is easy enough to have a terminal open on the side and pop it
up there.

Thomas

On 9 May 2012 16:55, Kieron Taylor <ktaylor at ebi.ac.uk> wrote:
> On 09/05/12 09:45, Andreas Kusalananda Kähäri wrote:
>>
>> On Wed, May 09, 2012 at 09:38:09AM +0100, PATERSON Trevor wrote:
>>>
>>> I agree entirely with Jay that the Doxygen documentation is extremely
>>> poorly designed and hard to read - is there any reason not to revert to the
>>> old perldoc format? OK it looks clunky compared to Doxygen - but IMHO
>>> readable content is more important than a cool style - or is that heresy to
>>> the Facebook generation?
>>
>>
>> One of the greatest benefits of the new doxygen-based documentation is
>> that you easily see the inherited methods in each sub-class.  This alone
>> is reason to not go back to the "perldoc" thingy we had before.
>>
>> I don't get the reference to Facebook.  Care to elaborate?
>>
>> Cheers,
>> A
>>
>
> Thanks Andreas. At the risk of further off-topic diversion, I can enumerate
> the other reasons for making the switch:
>
> Pros of Doxygen based system:
>
> Full comprehension of inheritance and inclusion for module dependencies
> Search with autocomplete
> Index by method name
> Automatic cross-linking between classes
> Scope for further improvement, developer support
>
> Cons:
> Too many views of the same information - kitchen sink approach
> Perl a bad fit for pure OO modelling
> "Programmer" lingo unfriendly to casual coders with no formal training
>
> Pros of PDoc (the old system):
> Bold and simple layout for individual modules
>
> Cons:
> HTML frames interfering with Ensembl web site.
> Click-through inheritance
> PDoc unmaintained and difficult to upgrade
> "Classic HTML" look
> Code for methods not next to method documentation
>
> I tried to implement proper inheritance in PDoc and failed. It was demanding
> almost a complete rewrite, as PDoc was not intended to be OO-aware from the
> ground up. When I first looked at it, the PDoc output was as obtuse and
> difficult to read as the Doxygen output appears to you.
>
> Doxygen is exceedingly flexible so there is scope for improving the
> presentation of the documentation. I hope I can find the time to do this.
>
> In addition, we are finding good results in our API training courses where
> we spend a few minutes briefing the users on how to use the documentation.
> In my opinion, new users on the courses are getting into the coding more
> quickly than with the PDoc system.
>
> It is not my call to make, but Ensembl is not likely to revert to the old
> system any time soon. The benefits outweigh the uncomfortable transition
> from one interface to another.
>
> --
> Kieron Taylor Ph.D.
> Ensembl Core software developer
>
> EMBL - European Bioinformatics Institute
> Wellcome Trust Genome Campus
> Hinxton, Cambridge CB10 1SD
> United Kingdom
>
>
> _______________________________________________
> Dev mailing list    Dev at ensembl.org
> List admin (including subscribe/unsubscribe):
> http://lists.ensembl.org/mailman/listinfo/dev
> Ensembl Blog: http://www.ensembl.info/