---------- Forwarded message ----------
From: Riccardo Pellarin <pellarin.riccardo@gmail.com>
Date: Mon, Aug 6, 2012 at 12:05 AM
Subject: Re: on documentation
To: Daniel Russel <drussel@gmail.com>

Hi Guys,

would like to share my thoughts on IMP documentation, maybe repeating
what we've already said. I think it is important, though, to share our experience.

Let's suppose I want to fit two structures and calculate the Calpha-rmsd,
a very simple task.

Was typing RMSD in the imp manual search field and got 36 entries.

1st problem: the entry titles are uninformative, unless you know exactly
what each module is supposed to do (statistic, atom, multifit etc, etc). 

Knowing a little bit of IMP I could filter the entries and remove all classes belonging
to multifit and em modules, for instance. Let's take the first seven entries which
might do what I want to do:

Member IMP::statistics::ConfigurationSetRMSDMetric::ConfigurationSetRMSDMetric
class IMP::atom::RMSDCalculator
Member IMP::atom::RMSDCalculator::RMSDCalculator
Member IMP::atom::RMSDCalculator::RMSDCalculators
class IMP::statistics::ConfigurationSetRMSDMetric
Member IMP::atom::get_pairwise_rmsd_score
IMP::atom::get_rmsd

2nd problem: I see a lot of redundancy in the list, and a lot of confusion:
classes and members are mixed together... why is that? Wouldn't it be cleaner
to separate them in two different lists?

Now, let's clean a little bit the list, my eyes go on these candidates:

class IMP::atom::RMSDCalculator
class IMP::statistics::ConfigurationSetRMSDMetric
Member IMP::atom::get_pairwise_rmsd_score
IMP::atom::get_rmsd

3rd Problem: there is not a single function that does a simple task
as an RMSD calculation, but there are many, with different flavors...
Probably many people implemented the same thing many times
because they didn't understand what was implemented before?

Let's have a look at the functions and see if they do what I want...
(as a side note, reading the documentation of IMP functions,
I really would like to leave notes on many of them....)

Let's start with IMP::atom::RMSDCalculator

Detailed Description

Fast rmsd calculation. Used to calculate rmsd between multiple 
transformation that operate on the same particles


Well, that is not detailed. 
What is a "fast rmsd"? No structural fitting I guess? What is the "rmsd between multiple
transformations" ? Maybe rigid body transformations? I start to doubt that this rmsd function is 
calculated between particles at all... 
Let's try to rewrite it. This is what I would like to read:

Short Description: Calculates the rmsd of a list of particles.

Detailed Description: Calculates the root mean square displacement (rmsd) of particles
subjected to rigid-body transformations. The rmsd calculation does
not perform structural best-fit alignment.
Usage: 
1) construct the class using a list of particles:
RMSDCalculator(particles)
2) get the rmsd using the method get_rmsd(trans3D1, trans3D2) 
where trans3D1 and trans3D2 are rigid body transformations of the
reference and displaced configurations, respectively.
Simple Example: ....

It would be cool if the short description appears in the search
page, along with the class name.

Let's go to the second function:  IMP::statistics::ConfigurationSetRMSDMetric

Detailed Description

Compute the RMSD between specified sets of particles in pairs of configurations, within a configuration set

this is even more cryptic. Maybe: 

Calculates the RMSD of a list of particles between all possible configurations pairs in a "configuration set", which is....

Strangely, this class has not get_rmsd(), but get_distance() method....
Is that the same?

Let's go to another example: IMP::atom::get_pairwise_rmsd_score
The measure quantifies the RMSD between the relative placements of two components compared to a reference relative placement. First, the two compared structures are brought into the same frame of reference by superposing the first pair of equivalent domains (ref1 and mdl1). Next, the RMSD is calculated for the second component

What are the components? Maybe subunits? What are the domains? Why the function is called rmsd_score? Is that different from the rmsd?

Ok I can go on for almost every function and method in IMP.

At the end, I'm completely unsure of what function I should use
for my task.... they all look the same.

Here's my proposal: Every function documentation must have these entries:

Short Description: (appears in the search page)
Detailed Description: 
[Algorithm Description: in some cases]
Usage: 
Simple Example: 

The developer might leave these fields empty, of course. 
When I search something, the first entries should be the 
ones which are more relevant and documented.
Or maybe, the search page should have Documented and Undocumented results. 
(where Undocumented is a function which is lacking a long documentation page).

Of course we cannot force people to write comprehensive documentation,
but at least we can give the user the option of choosing the functions which
are better documented: that will be bad for developers that write code which is
undocumented, since their code will never be used by somebody else.
As a user, I will be skeptical using something where the documentation fields 
are empty!

Sorry, that was long. Hope to hear your feedbacks