Necessity of comprehensive documentation
Hi everybody,
This days, as I use more and more the IMP API documentation and get more familiar with it, I feel that is extremely simple, rather useless if you don't know about the class you're using and the internal mechanisms, or somebody introduce you to it. Probably it also applies to my small contributions to the package, but I would like to raise my hand as one that would enjoy some effort (and I am willing to take the advice too) from the rest of the developers when documenting.
Thanks Javi
I completely agree, the API documentation is equivalent to looking at header files. I can suggest the following to enhance it:
1. we should have a description of the logic behind imp: how "representation, scoring, optimization" is translated to imp classes, what is the data flow (ScoreStates, Restraints) during optimization, how to setup your system accordingly. A similar description can exist for specific IMP modules. 2. Each class should contain explanation including it's goals, where it is used and a small usage example. This info should go into the API, to make it more useful.
Dina
2009/3/26 Javier Ángel Velázquez Muriel javi@salilab.org: > > Hi everybody, > > This days, as I use more and more the IMP API documentation and get more > familiar with it, I feel that is extremely simple, rather useless if you > don't know about the class you're using and the internal mechanisms, or > somebody introduce you to it. Probably it also applies to my small > contributions to the package, but I would like to raise my hand as one that > would enjoy some effort (and I am willing to take the advice too) from the > rest of the developers when documenting. > > Thanks > Javi > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev > >
Dina Schneidman wrote: > I completely agree, the API documentation is equivalent to looking at > header files. > I can suggest the following to enhance it: > > 1. we should have a description of the logic behind imp: how > "representation, scoring, optimization" is translated to imp classes, > what is the data flow (ScoreStates, Restraints) during optimization, > how to setup your system accordingly. > We probably can rip something out of one of the papers for this and put it in the Intoduction page.
> A similar description can exist for specific IMP modules. > Each module has a page where you can put as much description as you want (and you can add more pages as desired). They are currently quite minimal, but more is always good :-)
> 2. Each class should contain explanation including it's goals, where > it is used and a small usage example. This info should go into the > API, to make it more useful. > Any people should put examples in the examples dir (you can include them in the doxygen docs as is done for eg ClosePairsScoreState).
A few more comments: First, the documentation is getting fleshed out as requested. So any requests, comments are appreciated. Of course, the more specific the better. And even better if they are added to the bug tracker.
Also, the search engine built into the docs kind of sucks, but is still the best way of finding things. I would propose that we make the docs world readable, so we can then use google to search them.
Better overview documentation is definitely needed. The current source for an overview is the Introduction page, but that is somewhat minimal as it was written for a presentation (and lacks any graphics). So do people have thoughts on how to provide a better overview of IMP? One thing that would be nice would be a diagram for a typical setup showing when restraints and score states and things are evaluated.
The plan has been to have some larger examples taken from people's work to give an overview of how to use things, but these have not materialized yet and as a result the examples are still pretty trivial. Pleas for better examples have so far gone unanswered :-) As an added incentive, code added as example code can be inspected by other people and improved and such improvements can be folded back into your code.
Javier Ángel Velázquez Muriel wrote: > > Hi everybody, > > This days, as I use more and more the IMP API documentation and get > more familiar with it, I feel that is extremely simple, rather useless > if you don't know about the class you're using and the internal > mechanisms, or somebody introduce you to it. Probably it also applies > to my small contributions to the package, but I would like to raise my > hand as one that would enjoy some effort (and I am willing to take the > advice too) from the rest of the developers when documenting. > > Thanks > Javi > ------------------------------------------------------------------------ > > _______________________________________________ > IMP-dev mailing list > IMP-dev@salilab.org > https://salilab.org/mailman/listinfo/imp-dev >
participants (3)
-
Daniel Russel -
Dina Schneidman -
Javier Ángel Velázquez Muriel